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Note: This manual describes "the new Alto Operating System," which is thoroughly 
different from any Alto operating system operating in 1975! 



1. Introduction 

This manual describes the operating system for the Alto. The manual will be 

revised as the system changes. Parts of the system which are likely to be changed 

are so indicated; users should try to isolate their use of these facilities in routines 
which can easily be modified, or better yet, avoid them entirely, if possible. 

The system and its description can be separated into two parts: 

a) User-callable procedures, which are of two kinds: standard procedures which 
are always provided, and library procedures v/hich must 5e loaded with the 
user's program if they are d^ired. This manual describes only standard 
procedures; the library procedures are documented in the "Alto Packages 
Manual." 

b) Data structures, such as disk files and directories, which are used by the 
system but which are also accessible to user procedures and subsystems. 

The system is currently written almost entirely in Bcpl. Its procedures are invoked 
with the standard Bcpl calling sequence, and it expects the subsystems it calls to be 
in the format produced by the Alto Bcpl loader. 



2. Hardware summary 

This section provides an overview of the Alto Hardware. Briefly, every Alto has: 

a) A memory of 64k words of 16 bits each, plus parity. The cycle time is 
850ns. 

b) An emulator for the Nova instruction set, except the input/output 
instructions (which include MUL, DIV, HLT and the instructions which 
control the interrupt system). The only other incompatibilities are: 

1) Addresses are 16 bits, rather than 15, so that bit of an index 
register affects the addressing. 

2) Indirect addresses are also 16 bits, so that bit is part of the 
address, rather than specifying another level of indirection. 

3) Auto-increment and auto-decrement are not implemented. 

There are some new instructions which are listed in Table 2.1. The Alto 
executes emulated instructions in about 1.5 times the time required by the 
Nova 800: about 1.2 us for register instructions, 2 us for loads and stores. 

c) Secondary memory, which may consist of one or two Diablo 31 cartridge disk 
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drives, or one Diablo 44 cartridge disk drive. The properties of these disks 
are summarized in Table 2.2. 

d) An 875 line TV monitor on which a raster of square dots can be displayed, 
606 dots wide and 808 dots high. The display is refreshed from Alto 
memory under control of a list of display control blocks. Each block 
describes what to display on a horizontal band of the screen by specifying: 

the height of the band, which must be even; 

the width, which must be a multiple of 32; the space remaining on the 

right is filled with background; 
The indentation, which must be a multiple of 16; the space thus reserved 

on the left is filled with background; 
the color of the background, black or v/hite; ^ 

the address of the data (must be even), in which bits specify 

background. Each bit controls the color of one dot. The ordering is 

increasing word addresses and then bit numbers in memory, top to 

bottom and then left to right on- the screen; and a half -resolution flag 

which makes each dot twice as wide and twice as high. 

There is also a 16 x 16 cursor which can be positioned anywhere on the 

screen. If the entire screen is filled at full resolution, the display takes 

about 60% of the machine cycles and 30704D words of memory. 

e) A 44-key keyboard, 5-finger keyset, and mouse 

f) A Diablo printer interface 

g) An Ethernet interface 

h) Interfaces for analog-to-digital and digital-to-analog conversion, for TV 
camera input, and for a RS-232b (teletype) connection 

i) A real-time clock and an interval timer (see table 2.1 for brief descriptions) 



3. User-callable procedures 

This section describes the operating system facilities provided by procedures which 
can be called from user programs using the standard Bcpl calling sequence. All of 
these procedures are a permanent part of the operating system, automatically 
available to any user program. 

Although this manual describes a rather extensive set of facilities, which together 
occupy close to 12K words of memory, portions of the system can be deactivated, 
thus freeing the memory they use. When the user progi^am finishes execution, the 
deactivated portions can be retrieved from the disk and reinitialized. 

Default arguments: Many of the procedures given below have rather long argument 
lists, but have convenient defaulting schemes. The documentation decorates argument 
lists with default values. An argument followed by [exp] will default if omitted or 
zero to the value exp; an argument followed by [...expj will default if omitted to 
exp. Although Bcpl allows you to omit procedure arguments by using "nil," the called 
procedure cannot detect its use; it therefore cannot be the basis for defaulting 
arguments. 
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3.1, Facilities 

The facilities of the operating system fall into fairly neat categories; often this is 
because the operating system has simply loaded a standard library subroutine as part 
of its environment. This manual offers summarized documentation for the functions 
in the various software "packages;" more documentation can be found in the "Alto 
Software Packages Manual," (Note: Appendices to this manual include documentation 
of the packages most relevant to the operating system.) In outline, the operating 
system provides: 

- A "basic" resident that maintains a time-of-day clock, that processes parity 
error interrupts, and that contains the resident required to interface to Swat, 
the debugger. 

- The Bcpl runtime support module, which provides several functions (such as a 
stack frame allocator) that are necessary to permit Bcpl programs to run. 

- Disk drivers for transferring complete pages between memory and existing files 
on the disk. This is the BfsBase package. 

- Disk drivers for creating new files, and for extending or shortening existing 
files. This is the BfsWrite package. 

- A simple storage allocator that for managing "zones" of working storage. This 
is the Alloc package. 

- Disk "streams," which implement sequential byte or word I/O to the disk. 
This is the Streams package. 

- Disk directory management, which provides facilities for searching directory 
files for entries that associate a string name and a disk file. 

- A keyboard handler, which decodes keyboard interactions into a sequence of 
ASCII characters. 

- A display driver, which maintains a "system display," and handles the printing 
of characters on the display. This is the DStream package. 

- Miscellaneous functions, including (1) the "call subsystem" function, which 
reads a file produced by the Bcpl loader into memory and executes it; (2) 
allocation functions that manage the space not used by the operating system 
or the user code, providing a stack for the user program and fixed-size blocks 
that it may require; (3) the procedure for de-activating various portions of the 
operating system; and (4) additional utilities. 

3.2. Loading and Initialization 

The facilities of the operating system are made accessible to user progi'ams via static 
variables that refer to system p rocedures or system scalars. Because these objects 
are not defined in a users Bcpl ^progi'am, he must declare the names to be external. 
The Bcpl loader, Bldr, automatically reads the file Sys.Bk, which describes how to 
arrange that the user's references will match up with the operating system objects 
(for details, see Bldr documentation in the Bcpl manual). This arrangement does not 
require re-loading programs when objects in the operating system move. 

When a Bcpl program is read into the Alto memory, all of the system procedures 
described below will have been initialized. A region is reserved for allocating system 
objects (e.g., disk streams); currently, about 6 disk streams or equivalent can be 
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accomodated. If the space reserved is inadequate for your application, the system 
zone can be replaced with one constructed by the user's program. In addition, most 
procedures that create system objects have provision for an optional "zone" argument 
used for seizing space (see section 4.5). 

3.3. Errors 

Whenever the system detects an error for which the user program has not supplied 
its own error routine, the call SysErrfpl, errCode, p2, p3, ...) . is executed. The 
errCode is a number that identifies the error; the p's are parameters that add 
details. 

Normally, SysErr calls Swat (the debugger), which will print out an intelligible error 

message retrieved from the file Sys.Errors. The facilities of Swat (see "Alto 

Subsystems Manual") can then be used to interrogate the program state more fully, 
and ultimately to continue the computation or to abort it. 

3.4. Streams 

The purpose of streams is to provide a standard interface between programs and 
their sources of sequential input and sinks for sequential output. A set of standard 
operations, defined for all streams, is sufficient for all ordinary input-output 
requirements. In addition, some streams may have special operations defined for 
them. Programs which use any non-standard operations thereby forfeit complete 
compatibility. 

Streams transmit information in atomic units called items. Usually an item is a 
byte or a word, and this is the case for all the streams supplied by the operating 
system. Of course, a stream supplied to a program must have the same ideas about 
the kind of items it handles as the program does, or confusion will result. 
Normally, streams which transmit text use byte items, and those which transmit 
binary information use words. (The 16-bit quantity which Bcpl passes as an 
argument or receives as a result of a stream operation could be a pointer to some 
larger object such as a string, although the operating system implements no such 
streams. In this case, storage allocation conventions for the objects thus transmitted 
would have to be defined.) 

The user is free to construct his own streams by setting up a suitable data 
structure (section 4.2) which provides links to his own procedures which implement 
the standard operations. 

The standard operations on streams are (S is the stream; "error" means that Errors(S, 
ec) is executed, where ec is an error code): 

Gets(S) returns the next item; error if Endofs(S) is true 

before the call. 

Puts(S; I) v/rites I into the stream as the next item; error if 

the stream is read-only, if there is no more space 
or if there is some hardware problem. 

Resets(S) restores the stream to some initial state, generally 

as close as possible to the state it is in just after 
it is created. 

PutbaGks(S, I) modifies S so that the next Gets(S) will return I 

and leave S in the state it was in before the 
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Endofs(S) 
ClosesCS) 

StateofsCS) 
Errors(S, ec) 



Putbacks. Error if there is already a putback in 
force on S, 

true if there are no more items to be gotten from 
S. Not defined for output streams. 

destroys S in an orderly way, and frees the space 
allocated for it. Note that this has nothing to do 
with deleting a disk file. 

returns a word of state information which is 
dependent on the type of stream. 

reports the occurrence of an error with error code 
ec on the stream. When a system stream is 
created, Errors is initialized to SysErr (see section 
3.3), but the user can replace it with his own error 
routine. 



Streams are created differently depending on the device being accessed (disk, display, 
keyboard, or memory). The procedures for creating streams are described below. 



3.4.1. Disk streams 

The system distinguishes four kinds of object which have something to do with 
storing data on the disk: 



Disk: 



Disk file: 



File directory: 



Disk stream: 



A storage medium that is capable of storing data 
in various pages. Most operating system functions 
default the choice of disk to "sysDisk", a structure 
which describes drive of a Diablo model 31 
cartridge. 

A vector of bytes of data held on some disk, 
organized into pages for some purposes. A file 
exists only on the disk (except that parts of it 
may be in memory if an output stream is 
associated v/ith it) and is named by an 80-bit 
entity called a file pointer (FP). 

A disk file which contains a list of pairs <string 
name, FP>. Documentation on the format of the 
file can be found with the BFS package 
documentation contained in an appendix to this 
manual. 

Used by a program to transfer information to or 
from a disk file. A stream exists only in memory 
and is named by a pointer to a data structure. 



The procedures that operate on disk streams are described in documentation for the 
"Streams" software package contained in an appendix to this manual. Below is a 
summary list of the functions (in addition to the generic functions described above): 

CreateDisliStream(filePtr, type [ksTypeReadWrite], itemSize [wordltem], Cleanup 

f Noop], errlltn [SysErr], zone [sysZone], loglnfo [Oj, 
disk [sysDisk]) = a disk stream, or if an error is 
encountered while initializing the stream. filePtr is 
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the sort of object stored in a file directory. Legal 
types are ksTypeReadOnly, ksTypeReadWrite, and 
ksTypeWriteOnly. Legal item sizes are wordltem 
and charltem. 

CleanupDiskStream(s) Flush any buffers to the disk. 

ReadBlock(s, address, count) = actualCount. Read up to count words from the 

stream into consecutive memory locations; return 
the actual number of words read. 

WriteBlock(s, address, count) Write count words from consecutive memory 

locations onto the stream. 

LnPageSizeCs) = log (base 2) of the page size, in words, of the 

files manipulated by the stream. 

PositionPage(s, page) Positions the file to byte of the specified page 

(page 1 is the first data page). 

PositionPtr(s, byteNo) Positions the file to the specified byte of the 

current page. 

FileLength(s, filePos []) = Length. Returns number of bytes in file; 

positions stream to the last byte. 

FilePos(s, filePos []) = Pos. Returns the current byte position in the 

file. 

SetFilePos(s, filePos) or SetFilePos(s, HighOrder, LowOrder) Sets the position of 

the file to the specified byte. 

GetCurrentFa(s, fileAddress) Returns the current file address. 

JumpToFa(s, file Address) Positions the file to the specified address (usually 

obtained from GetCurrentFa). 

GetCompleteFa(s, completeFile Address) Returns a complete file address, 

including a filePtr. 

TruncateDiskStream(s) Truncates the file to the current position. 

ReadLeaderPage(s, address) Reads the 256-word leader page of the file into 

consecutive locations starting at address. 

WriteLeaderPage(s, address) Writes 256 words onto the leader page of the file. 

The operating system also contains a package for dealing v/ith files at a lower level, 
the "Bf s" (Basic file system) package. 

Disk Errors: The system will repeat five times any disk operation which causes an 
error. On the last three repetitions, it will do a restore operation on the disk first. 
If five repetitions do not result in an error-free operation, a (hard) disk error occurs; 
it is reported by a call on Errors for the stream involved. 

Logging disk transactions: The operating system reports various logging information 
on the file Sys.Log. Normally, all file openings, creations and deletions are recorded. 
In order to speed up logging, the Sys.Log iile is kept "open" all the time, and 
relevant file state is saved in memory. 
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LogOpen(zone) Opens the log file on sysDisk, and saves vital state 

in the given zone. LogOpen(sysZone) is executed at 
completion of each program execution, to make sure 
the log is open when the next program is invoked. 

MakeLogEntry(logType, filePtr, loglnfo [0], zone [sysZone], disk [sysDiskT) This 

function makes an entry of type logType in tne file 
Sys.Log (see definitions in AltoFileSys.d and Disks 
documentation). 



LogClose(zone) 



Closes the log file, which insures that no 
inform.ation about the state of the log file is saved 
in memory. LogClose(sysZone) is performed by the 
finish operation. 



3.4.2. Display streams 

Display streams are implemented with the "DStream" package, described in separate 
documentation contained in an appendix to this manual. Below is a list of the 
functions included (in addition to the generic stream functions): 

CreateDisplayStream(nLines, pBlock, IBloek, Font [sysFont], wWidth [38], options 

TDScornpactleft+DScompactright], zone [sysZonej) = a 
display stream. pBlock is the address of a region 
IBlock words long for the display bitmap. nLines is 
the number of text lines in the stream. This 
procedure does not commence displaying the stream 
text — see ShowDisplayStream. 

Shov/DisplayStream(s, how [DSbelow], otherStream [dsp]) This procedure controls 

the presentation of the stream on the screen. If 
how is DSbelow, the stream will be displayed 
immediately" below otherStream; if DSabove, 
immediately above; if DSalone, the stream will 
become the only display stream displayed. If hov/ 
is DSdelete, the stream s will be removed from the 
display. For DSalone and DSdelete, the third 
argument is needless. 



GetFont(s) 
SetFont(s, font) 

ResetLine(s) 

GetBitPosCs) 
SetBitPos(s, pos) 

GetLinePos(s) 

SetLinePos(s, pos) 



Returns current font. 

Sets current font 
documentation). 



(use carefully 



see 



Erases all information on the current line and 
resets the position to the left margin. 

Returns the horizontal position of the stream. 

Sets the horizontal position on the current line 
(use carefully — see documentation). 

Returns the index of the line into which characters 
are presently being put. 

Sets the line number into which subsequent 
characters will be put. 
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InvertLine(s, pos) Inverts the black/white sense of the line given by 

pos. 

EraseBits(s, nBits, flag [0]) Erase bits moving forward (nBits>0) or backward 

(nBits<0) from the current position. Set to 
background if flag=0; to the complement of the 
background if flag=l; invert present values if flag=- 
1. 

GetLmarg(s); SetLmarg(s) Get and set left margin for the current line. 

GetRmarg(s); SetRmarg(s) Get and set right margin for the current line. 

CharWidth(StreamOrFont, char) Get the width of the character, using the 

specified font or the current font in the specified 
stream. 

The "system display stream" is always open, and can be accessed by the system scalar 
"dsp." 

3.4.3. Keyboard Streams 

There is a single keyboard stream in which characters are buffered. The stream is 
always open, and may be accessed through the system scalar "keys." The only non- 
null operations are Gets; Endofs, which is true if no characters are waiting; and 
Resets," which clears the input buffer. 

The keyboard handler periodically copies the mouse coordinates into the cursor 
coordinates, truncating at the screen boundary. This function is governed by the 
value of a cell referenced by @ IvCursorLink; if it is zero, the function is disabled. 

Low - level keyboard functions . Although the standard keyboard handler contains no 
facilities for detecting transitions of keyset or mouse keys, a user function may be 
provided that will be called 60 times a second and can extract relevant information 
from a table passed to it. The call SetKeyboardProc(uKbProc, stack, stackLength) 
will install uKbProc as the user procedure; stack is a vector that v/ill be used for 
stack space when uKbProc is run [you must provide enough!). SetKeyboardProcQ will 
reset the keyboard handler, and cease calling uKbProc. (Note: If the program has 
used the Junta procedure, the user keyboard procedure must be deactivated during a 
Counter Junta or finish unless all its state lies below OsFinishSaf eAdr.) If active, 
every 16 milliseconds, the keyboard handler will execute uKbProc(tab), where tab 
points to a data structure defined by the KBTRANS structure (see the file 
SysDef s.d). The Transition word is non-zero if a key transition has been detected; 
GoingUp or GoingDown tell which sort of transition has occurred; and Keylndex gives 
the key number. KeyState is a 5-word table giving the state of the keys after the 
transition has occurred: if a key. with Keylndex=i is presently dov/n, bit (i rem 16) 
of v/ord (i div 16) will be 1. The entries CursorX and CursorY give the current 



of 



location oi the cursor. 

The value returned by uKbProc determines subsequent processing. If true is 
returned, the operating system treats the key transition (if any) according to normal 
conventions. If false is returned, the operating system assumes that ufebProc has 
performed whatever processing is intended, and the interrupt is simply dismissed. 

Keylndex values are tabulated below. Keys are normally given by their lower-case 
marking on the key top; those with more than one character on their tops are 
specified by <name>. <X> are unused bits; <blank-top> is the key to the right of the 
<bs> key; <blank-middle> to the right of <return>; and <blank-bottom> to the right 
of <shift-right>. 
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Values Keys 

0-15 5 4 6 e 7 d u vio k - p / \ <lf> <bs> 

16-31 3 2 w qsa9iixol,'] <blank-middle> <blank-top> 

32-45 1 <esc> <tab> f <ctrl> c j b z <shift-left> . ; <return> <- <del> <X> 

48-63 r t g y h 8 n m <lock> <space> [ = <shift-right> <blank-bottom> <X> <X> 

64-71 unused 

72-76 Keyset keys in order, left=72; right=76 

77 RED [or left or top) mouse button 

78 BLUE (or right or bottom) mouse button 

79 YELLOW (or middle) mouse button 

As an aid to interpreting Keylndex values, the system scalar kbTransitionTable points 
to a table, indexed by Keylndex, that gives a KBKEY structure for the key; if it is 
zero, the operating system has no standard interpretation of the key. 

3.4.4. Fast Streams to Memory 

The operating system also contains procedures that allow very efficient stream I/O to 
memory blocks. These functions, described in the Streams package documentation, 
allow one for example to use much more memory buffering for disk transfers than 
normally allocated by the disk stream mechanism. 

3.5. Directory Access 

Most user programs do not concern themselves with file pointers, but use system 
routines v/hich go directly from string names to streams. By a "file name" we mean 
a string which can be converted into a file identifier by looking it up in a 
directory. File names are arbitrary Bcpl strings which contain only upper and lower 
case letters, digits, and characters in the string "+-.!$". File names are stored in 
directories as they are typed, but no distinction is made between upper and lower 
case letters when they are looked up. Dots (".") are used to separate file names into 
parts. If there is more than one part, the last part is called the extension , and is 
conventionally used much like extensions in Tenex. The interpretation ol exclamation 
mark ("!") is special; if a file name ends with a ! followed only by digits, the digits 
specify the file version number. 

^ lool^^P name , presented to one of the directory functions given below, is usually a 
file name. However, it may optionally specify the name of a directory in which to 
look for the file (or record the new file). The lookup name is processed from left 
to right. If the character "<" appears at the head of the lookup name, the system 
directory ("SysDir.") becomes the "current" directory; whenever the character ">" 
follows a name, tne name is looked up in the cui'rent directory and that file 
becomes the new current directory. If no directory is specified in the lookup name, 
the "working directory" is assumed. Example: "<dir>fil." will look up dir in the 
system directory SysDir, and will then look up fil in dir. Any illegal characters in a 
lookup name are replaced with "-" characters. 

File Versions: The file system also supports multiple versions of the same file; this 
feature may be enabled or disabled when the operating system is installed. The 
version number is recorded by appending an exclamation mark and the decimal 
version number to the file name; file names without version numbers appended act 
as if they are "version 0." The OpenFile function uses lookup names and version 
control information to locate a desired file. If the lookup name contains a version 
number (e.g., "Sys.Errors!3."), then no version defaulting is done— the lookup operates 
on precisely the file specified. (This processing is identical with versions enabled and 
disabled.) 
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If the lookup name does not specify a version number and file versions are enabled, 
then the versionControl parameter specifies how defaulting is to be done fin the 
definitions, "oldest" refers to the file with the "lowest" version number; latest" 
refers to the file with the "highest" version number): 



verLatest 
verLatestCreate 



verOldest 
verNew 



verNev/ Always 



The latest version is used. 

The latest version is used. If the file does not 
exist, it is created with version number (i.e., no 
number will be appended explicitly to the file 
name): this is to prevent needless accumulation of 
version numbers in system-related files (.e.g, .Run 
files). 

The oldest version is used. 

A new file will always be created. A system 
parameter, established when the system is installed, 
determines how many old versions will be preserved. 
If that default should be overriden, just add the 
desired number of versions to verNew, e.g. a 
versionControl value of verNew+4 will create a new 
file and retain at most three older versions. 

This version option may reuse disk pages allocated 
for the oldest version of the file, but the serial 
number and file name will of course be changed. 
If (nev/est~oldest)+l is greater than or equal to the 
number of versions to keep, oldest is reused in this 
fashion to become version newest+1. For example, 
if verNew is specified, 2 versions are to be kept, 
and foo!2 and foo!3 exist, verNew will create the 
file foo!4 by remaking the old file foo!2. Note that 
this calculation does not verify that all versions 
between oldest and newest actually exist. 

If only one file matches the lookup name, and its 
version number is 0, the file is simply overwritten 
Qike verLatestCreate); a new version is not created. 

If no files of the given name exist, version number 

of the file is created (i.e., no version number is 
explicitly attached to the file name). The 
verNewAlways option (below) can be used if version 

1 should be created. 

Similar to verNew, but if no earlier version of the 
file exists, version 1 is created. 



If versions are not enabled, then exact matches are performed on the entire file 
name. Thus, if the file "Sys.Errors!2" is present on a disk with versions disabled, 
the lookup name "Sys.Errors" will not match this file; the lookup name "Sys.Errors!2" 
will. 

The following function creates a disk stream (see above) in conjunction with the 
Alto directory structure: 

OpenFile(lookupname, ksType [ksTjnpeReadWrite], itemSize [wordltem], 

versionControl [if ksType=ksTypeReadOhly then 
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verLatest else if ksType=ksTypeWriteOnly then 
verNew else verLatestCreate], hintFp TOT, errRtn 
[SysErr], zone [sysZone], loglnfo [0], disk tsysDisk], 
Creates tream [CreateDiskStream]) = a disk stream, 
open on the specified file, or if the open is 
unsuccessful for some reason. This routine parses 
the lookup name, searching directories as needed. 
After applying version control fe.g., making a new 
version), it calls CreateStreamffilePointer, ksType, 
itemSize, Noop, errRtn, zone, loglnfo, disk), and 
returns the value of that call. 

If hintFp is provided, it is assumed to be a file 
pointer (FP) that "hints" at the correct 
identification of the file. Before searching a 
directory, OpenFile will try using the hint to open 
the file, quickly returning a stream if the hint is 
valid (though no name or version checking is done). 
If the hint fails and lookupname is non-zero, the 
name will be parsed and looked up in the normal 
fashion. hintFp will be filled in with the correct 
file pointer. Note: If you wish to use standard file- 
lookup procedures, but to have the FP for the 
resulting file returned to you, zero the hintFp 
vector before calling OpenFile. In this case, the 
value of hintFp is not used in the lookup, but is 
filled in with the results. 

= OpenFile(0, 0, 0, 0, hintFp) 

versionControl [verOldest], errRtn [SysErr], zone 
[sysZone], loglnfo [0], disk [sysDiskJ) = success. 
Deletes the file on the disk and removes the 
corresponding entry from the directory specified in 
lookupname. Returns "true" if a file was correctly 
found and deleted, otherwise "false." 

SetWorkingDir(name, fp, disk [sysDisk]) Sets the "current" directory for further 

lookups on the given disk. When the system is 
booted, the current directory is set to "<SysDir." 



OpenFileFromFp(hintFp) 
DeleteFileQookupname, 



3.5.1. Lower-level directory functions 

Several functions are provided for those who v/ish to deal with directories and file 
names at a lower level. The format of an Alto file directory is documented in the 
Disks documentation; definitions appear in AltoFileSys.d. 

FindFdEntry(s, name, compareFn [0], dy [], hd [], versionControl [verLatest], 

extraSpace [0]) = a word pointer into the stream s 
of a directory entry, or -1 if no entry is located. If 
compareFn is 0, normal comparison of file names 
and version control is performed; the result is a 
directory entry in dv, and a hole descriptor (hd) 
for a hole large enough to include the name, a new 
version number, and extraSpace words. 

Otherwise, compareFn is a user procedure that is 
invoked as each file name is read from the 
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directory: compareFn(name, nameRead, dvRead). 
nameRead is the Bcpl name extracted from the 
directory; dvRead is the dv extracted from the 
directory; and name is simply the second argument 
passed to FindFdEntry (which need not be a 
string). If compareFn returns false, the directory 
scan halts; the value of FindFdEntry is the byte 
position in the stream. If compareFn returns true, 
the search proceeds. 

Strategic note: If compareFn is TruePredicate, the 
directory is simply scanned in order to locate a 
hole large enough for extraSpace v/ords. The result 
is saved in the hd hole descriptor, which may be 
passed to MakeNewFdEntry. 

MakeNewFdEntry(s, name, dv, hd, extraStuff) makes a directory entry: dv is a 

pointer to a DV structure for the first part of the 
entry; name is a Bcpl string that is recorded after 
the entry (this string must be a legal internal file 
name, with the dot ." appended), and extraStuff is 
a pointer to a vector of additional stuff that will 
be entered following the name. The hd parameter 
is a pointer to a "hole descriptor" as returned from 
FindFdEntry. 



Dele teFdEn try (s, pos) 



Strip Version(string) 



Deletes the directory entry at byte location pos of 
the directory open on stream s. 

= version number. This function strips a version 

number, if any, from the end of the string 

argument, and returns the number (0 if no version 
specified). If, after stripping, there is no final "." 
on the string, one is appended. 



AppendVersion(string, versiorL^ppends a version number and final 

string. 



to the 



WriteDiskDescriptor() 



ReadDiskDescriptor() 



If changes have occurred, the copy of the disk 
descriptor for sysDisk that resides in memory is 
written onto the disk file "DiskDescriptor." 

This function restores the copy of the disk 
descriptor for sysDisk that resides in memory from 
the disk file "DisldDescriptor," 



3.6. Memory management 

Table 3.1 shov/s the layout of memory. Table 3.2 tells how to obtain the current 
values of the symbolic locations in Table 3.1. The free space (EndCode to StackEnd) 
can be manipulated as follows: 



GetFixed(nwords) 



FreeFixed(pointer) 



returns a pointer to a block of nwords words, or 
if there isn't enough room. It won't leave less 
than 100 words for the stack to expand. 

frees a block provided by GetFixed. 
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FixedLeftO 



SetEndCode(new Value] 



returns the size of the biggest block which 
GetFixed would be willing to return. 

resets endCode explicitly. It is better to do this 
only when endCode is being decreased. 



The allocator is not very bright. FreeFixed decrements endCode if the block being 
returned is immediately below the current endCode (it knows because GetFixed puts 
the length of the block in the word preceding the first word of the block it returns; 
please do not rely on this, however, since there is no guarantee that later allocators 
will use the same scheme). Otherwise it puts the block on a free list. When 
another FreeFixed is done, any blocl^ on the free list which are now just below 
endCode will also be freed. However, the allocator makes no attempt to allocate 
blocks from the free list. 



3.7. The Alloc allocator 

The operating system includes a copy of the Alloc package; documentation is 
contained in an appendix to this manual. 

InitializeZone[start, length, OutOfSpaceRoutine [...SysErr], MalFormedRoutine 

[...SysErr]) = a "zone.' These zones are compatible 
with the "zone" arguments to operating system 
functions (e.g., sysZone). 

AddToZone(zone, block, length) Adds block to the zone. 

Allocate(zone, length, returnOnNoSpace [false], even [false]) = pointer to a block 

of length words allocated from zone. If even is 

true, the pointer is guaranteed to be a even 
number. 



Free(zone, ptr) 
CheckZone(zone) 



Returns the block pointed to by ptr to the zone. 

Performs a consistency check on the zone data 
structure. 



3.8. The Basic File System 

A set of procedures for driving the disk hardware for Diablo Model 31 and 44 disk 
cartridges is included in the operating system. These functions are documented in 
the "Disks" documentation, appended to this manual. 



3.9. Objects 

It is often convenient to define an abstract object and its operations by a single 

entity in the Bcpl language. As the largest entity Bcpl can deal with is a 16-bit 
number, we must use a pointer to a structure of some kind that defines both the 

procedures and data associated with the object. Streams, Zones and Disks are 

examples of such abstract objects. Such objects are typically defined by a structure 
such as: 



structure ZN: 



Allocate 

Free 

Base 



word '^^^B 

word //Op 

word //Val 
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Length 



word 



//Val 



where the Op's point to procedures and the Val's are data for the structure. A 
tjrpical call on one of the abstract procedures is thus (zone»ZN.AllocateXzone, argl, 
arg2, arg3). The virtue of such an arrangement is that any structure that simulates 
the effects of the procedures can pose as a Zone. 

In order to encourage the use of such objects, the operating system has very 
efficient implementations for this calling mechanism: 

CallOCs, a, b, ...) Does (s!0)(s, a, b, ...) 

Calll(s, a, b, ...) Does (s!lXs, a, b, ...) 

Call2, Calls, Call4, Call5, Call6, Call7, Call8, Call9 analogously. 

Thus, the operating system defines Allocate=CallO, and Free=Calll, consistent with the 
Alloc package described above. Note for assembly-language programmers: the Callx 
functions actually enter the proper function at the second instruction, having already 
executed a STA 3,1,2 to save the return address. 



3.10. Miscellaneous 

This section describes a collection of miscellaneous useful routines: 



Wss(S, string) 

Ws(string) 

Wl(string) 

WnsCS, n, nc [0], r[-10]) 



Wos(S, n) 
Wo(n) 

TruePredicateQ 

FalsePredicateQ 

NoopQ 

Dvec(caller, nVl, nV2, ...) 



writes the string on stream S. 

writes the string on the system display stream, dsp. 

Ws(string), followed by a carriage return. 

writes a number n to stream S, converting using 
radix abs(r). At least nc characters are delivered 
to the stream, using leading spaces if necessary. 
The number is printed in signed notation if r<0, in 
unsigned notation if r>0. 

writes an unsigned octal representation of n on 
stream S. 

v/i'ites an unsigned octal representation of n on the 
display stream. 

always returns -1. 

always returns 0. 

null operation; returns its first argument if any. 

this routine allocates "dynamic" vectors in the 
current frame, caller is the name of the procedure 
calling Dvec. The use of the routine is best given 
with an example: the routine Shov/Off wants two 
vectors, VI and V2: 



let ShowOff(Vllength,V21ength) be 
let Vl=Vllength 
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let V2=V21ength 

Dvec(ShowOf f , Iv VI, Iv V2) 

// now VI points to a block Vllength+1 words long 

//and V2 points to a block V21ength+1 words long 



Warning: any addresses that point into the stack 
frame of ShowOff before it is moved by the Dvec 
call will not be correct after the call. Thus, for 
example, a "let a=vec 10" before the call will cause 
the address in a to be useless after the call. 

DefaultArgsQvNa, base, dvl, dv2, ) Utility procedure to fill in default 

arguments. IvNa points to the "numargs" variable in 
the procedure; abs(base) is the number of initial 
arguments that are not to be defaulted; the dvj are 
the default values p^H)- If base<0, then an 
actual parameter of zero v/ill cause the default to 
be installed; otherwise only (trailing) omitted 
parameters are defaulted. Thus: 

let Mine(how, siz, zone, errRtn; numargs n) be 

DefaultArgs(lv n, -1, 100, sysZone, SysErr) 

] 

will default arguments siz, zone, errRtn if missing 
or zero to 100, sysZone and SysErr respectively. 
Note that Bcpl will allow you to omit parameters 
in the middle of a parameter list by using "nil," 
but Default Args has no way of knowing that you 
did this. 

MoveBlock(dest, src, count) Uses BLT: for i=0 to count- 1 do dest!i=src!i. 

SetBlock(dest, val, count) Uses BLKS: for i=0 to count-1 do dest!i=val. 



Zerofdest, count) 
Usc(a, b) 

DoubleAddCa, b) 



Enablelnterrupts() 
Disablelnterrupts() 
StartlO(acO) 

IdleQ 



Same as SetBlock(dest, 0, count). 

Use performs an unsigned compare of a and b and 
returns -1 if a<b, it a=b, 1 if a>b. 

The parameters a and b each point to 2-word 
double-precision numbers. DoubleAdd does a<-a+b. 
Note that subtraction can be achieved by adding 
the two's complement; the two's complement is the 
one's complement (logical negation) plus 1. 

Enables Alto interrupt system. 

Disables interrupt system. 

Executes the SIO emulator instruction with its 
argument in acO. Thus StartIO(#100000) will boot 
the Alto if it has an Ethernet interface. 

This procedure is called whenever the operating 
system is waiting for something to happen (e.g., a 
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Timer(tv) 
DayTime(dv) 



SetDayTimeCdv) 



EnumerateFp(proc) 
CallSwatCsl, s2) 



keyboard character to be struck, or a disk transfer 
to complete). The static Ivldle points to the 
operating-system copy of the procedure variable so 
that programmers may install their own idle 
procedures by executing "@lvIdle=MyIdle". 

Reads the 32-bit millisecond timer into tv!0 and 
tv!l. Returns tv!l as its value. 

Reads the current time-of-day . (32 bits, with a 
grain of 1 second) into dv!0 and dv!l. Returns dv 
as its value. (Subroutines for converting time-of- 
day into more useful formats for human 
consumption are available in GTime.c. See 
subroutine package documentation, under Time.) 

Sets the current time-of-day from dv!0 and dv!l. 
(Normally it should not be necessary to do this, as 
the time is set when the operating system is 
booted and has an invalid time. Thereafter, the 
timer facilities in the operating system maintain 
the current time.) 

For every file pointer saved by the system (e.g., 
fpComCm, fpRemCm, etc.), call proc(fp). 

This function invokes an explicit "call" on Swat. 
Either of the arguments that appears to be a Bcpl 
string will be printed out by Swat, 



3.10.1. Routines for Manipulating Bcpl Frames 

The following routines ease massaging Bcpl frames for various clever purposes such as 
coroutine linkages. See section 4.7 for a description of the data structures involved. 



FrameSize(proc) 

MyFrameO 

Caller3Frame(f) 

FramesCaller(f) 

CaliFrame(f, a, b) 

GotoFrame(f, a, b) 
CoCall(a, b) 
CoReturn(a, b) 
ReturnTo(label) 



Returns the size of the frame required by proc. 

Returns the address of the current frame. 

Returns the address of the frame that "called" the 
frame f (if f is omitted, the current frame is 
used). 

Returns the address to which the caller of frame f 
sent control, provided that he made the call with a 
normal instruction (jsrii, jsris). If error, returns 0. 

Sends control to frame f and links it back to this 
one (i.e., when f returns, the CallFrame call 
returns), a and b are optional arguments. 

Like CallFrame,/but does not plant a return link. 

CallFrame(CallersFrame(), a, b) 

Like CoCall, but does not plant return link. 

Returns to a given label in the frame of the caller. 
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GotoLabel(f, label, v) Sends control to the specified label in the specified 

frame, and passes v in AGO. 

RetryCall(a, b) Repeats the call which appears to have given 

control to the caller with a and b as the first 2 
arguments, and the other arguments unchanged. 
There are certain ways of calling functions which 
cannot be retried properly. In particular, the 
address of the procedure must be the value of a 
static or local variable; it cannot be computed. 
Thus "a»proc(s, b)" cannot be retried, but "let 
pr=a»proc; pr(s, b)" can be retried. 

ReturnFrom(fnOrFrame, v) Looks for a frame f which is either equal to 

fnOrFrame, or has FramesCaller(f3 equal to 
fnOrFrame. It then cuts back the stack to f and 
simulates a return from f with v as the value. If 
error, it returns 0. 

3.11. Subsystems and user programs 

All subsystems and user programs are stored as "Run files", which norm-ally have 
extension ".Run". Such a file is generated by Bldr and is given the name of the 
first binary file, unless some other name is specified for it. The format of an Alto 
run file is discussed in section 4.8 and in the Bcpl manual. 

CallSubsys(S, pause [false], doReturn [false], userParams [0]) will read in a run file 
and send control to its starting address, where S is an open disk stream for the file, 
positioned at the beginning of the file. If pause is true, the message "Pause to 
Swat" is typed out just before the program gets control; typing any key will proceed. 
(doReturn may someday be implemented, and will allow a return to the caller after 
the called subsystem "finishes.") userParams is a pointer to a vector flength up to 
lUserParams) of parameters which will be passed to the called suoystem. The 
parameters are formatted according to conventions given in SysDefs.D (structure UPE): 
each parameter is preceded by a word that specifies its type and the length of the 
block of parameters; a zero word terminates this list. When the Alto Executive 
invokes a progi'am with CallSubsys, it passes in iiserParams an entry with type 
globalSwitches which contains a list of ASCII values of global switches supplied after 
the program name. 

The open stream is used to load the program into Alto memory according to 
placement information included in the file. The stream is then closed; no other open 
streams are affected. 

The program is started by a call to its starting address, which will normally be the 
first function of the first file . given to Bldr. This function is passed three 
arguments. The first is the 32 word layout vector for the progi'am, described in the 
Bcpl manual. The second is a pointer to a vector of parameters provided by the 
caller (the userParams argument to CallSubsys). The third is the "complete file 
address (CFA) for a particular point in the file that was used to load the program. 
If no overlays are recorded in the Run file, this point is the end of file. If 
overlays are contained in the file, the CFA points to the first word of the first 
overlay section (this can be used as a hint in a call to OpenFile when loading 
overlays contained in the same file). 

Subsystems conventionally take their arguments from a file called Com.Cm, which 
contains a string which normally is simply the contents of the command line which 
invoked the subsystem (see section 5 J. The subroutine package GP contains a 
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procedure to facilitate reading this string according to the conventions by which it is 
normally formatted. This is not a standard routine but must be loaded with vour 
program. (For more information on GP, see the "Alto Software Packages Manual.") 

3.12. Finish — - Terminating Execution 

When a program terminates operation, it "finishes," returns to the operating system 
and ultimately to the Executive. A program may finish in several ways: 

Bcpl return If the main function in the user program (the one 

invoked by CallSubsys) ever returns, the program 
finishes. Equivalent to OsFinish(fcOK3. 

Bcpl finish If the "finish" construct is executed in a Bcpl 

grogram, it terminates. Equivalent to 

»sFinish(fcOK). 

Bcpl abort If the "abort" construct is executed in a Bcpl 

grogram, it terminates. Equivalent to 

>sFinish(fcAbort). 

Swat abort If, during program execution, the "left shift" key 

and the "Swat key" (lower-rightmost key on the 
keyboard) are depressed concurrently, the program is 
aborted. Similarly, if the <control>K ("Mil") 
command is typed to Swat, the program is aborted. 
Both are equivalent to OsFinish(f cAbort). 

OsFinish(fCode) An explicit call to this function will also terminate 

execution. The value of fCode is saved in the static 
OsFinishCode, which may be examined by the 
Executive and the next program that it invokes. 
Values of fCode presently defined are: fcOK=0; 
fcAbort=l. 

When a progi'am finishes, the value of the finish code is first recorded. Then, if 
the value of the static UserFinishProc is non-zero, the call 
UserFinishProc(OsFinishCode) is performed before restoring the operating system state. 
This facility is useful for performing various clean-ups. (Note: To set 
UserFinishProc, it is necessary to execute SlvUserFinishProc = value.) In order to 
permit independent software packages to provide for cleanups, the convention is that 
each initialization procedure saves the present value of UserFinishProc and then 
replaces it with his procedure. This procedure will do the cleanups, restore 
UserFinishProc, and return: 

// Initialization 

static savedUFP 

savedUFP=@lvUserFinishProc 

@lvUserFinishProc=MyCleanUp 

//The cleanup procedure 

let MyCleanUp(code) be 

... cleanups here 
@lvUserFinishProc=savedUFP 

I 
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Finally, control is returned to the operating system, which resets the interrupt 
system, updates the disk allocation table, and invokes the executive anew. 



3.13. Junta 

This section describes some procedures and conventions that can be used to permit 
exceptionally large progi*ams to run on the Alto, and yet to return cleanly to the 
operating system. The basic idea is to let a program de-activate various operating 
system facilities, and thereby recover the memory devoted to the code and data used 
to implement the facilities. To this end, the system has been organized in a series 
of "levels:" 



levBasic 



levBuffer 
levFilePointers 

levBcpl 
levStatics 
levBFSbase 
levBFSwrite 

lev Alloc 

levStreams 

levDirectory 

levKeyboard 

levDisplay 

levMain 



Basic resident, including parity interrupt processing, 
time-of-day maintenance, the resident interface to 
the Swat debugger, and the initial processing for 
OsFinish. Important system state is saved here: 
EventVector, UserName, UserPassword, OsFinishCode. 
(Approximate size: 1000 words) 

The system keyboard buffer (see section 4.6). 
(Approximate size: 100 words) 

File hints. This region contains "file pointers" for 
frequently referenced files. (Approximate size: 70 
words) 

Bcpl runtime routines. (Approximate size: 300 
words) 

Storage for most of the system statics. 
(Approximate size: 300 words) 

Basic file " system "base" functions, miscellaneous 
routines. (Approximate size: 1300 words) 

Basic file system "write" functions, the disk 
descriptor (used to mark those pages on the disk 
which are already allocated), interface to the time~ 
of-day clock. (Approximate size: 1200 words) 

The Alloc storage allocation package. (Approximate 
size: 500 words) 

Disk stream procedures. (Approximate size: 2700 
words) 

Directory management procedures. (Approximate size: 
1800 words) 

Standard keyboard handler. (Approximate size: 500 
words) 

Display driver (although the storage for the display 
bitmap and for the system font lie belowj. 
(Approximate size: 1600 words) 

The "Main" operating system code, including 
utilities, CallSubsys, and the Junta procedure. 
(Approximate size: 1000 words) 
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levCompat Compatibility level containing code that aims to 

implement compatibility with the old Alto operating 
system. (Approximate size: 1000 words) 

Below levCompat, where the stack starts, the 

system free-storage pool is located. Here are kept 

stream data structures, the system font, and the 

system display bitmap. (Approximate size: 6000 
words) 

This table of levels corresponds to the order in which the objects are located in the 
Alto memory: levBasic is at the very top; the bottom of levCompat is the highest 
location for the Bcpl stack. 



The "Junta" function is responsible for de-activating these levels, 
the space to be reclaimed. When a program that has called 
finish, it calls OsFinish in the normal way. • OsFinish performs 
reading in portions of the operating system from the boot file 
internal state of those levels that v/ere previously de-activated, 
with the finish, calling the Executive, etc. 



thereby permitting 
Junta is ready to 
the "counter-junta," 
and rebuilding the 

and then proceeds 



During the counter- junta process (which takes about 1/2 second), the display and 
interrupt system can continue to be active, provided that the code and storage they 
use lies below the address that is the value of OsFinishSafeAdr. This permits a 
token display to remain; also a keyboard handler can continue to sense key strokes 
and record characters in the system keyboard buffer. 



Junta(levName, Proc) 



...finish... 



Counter Junta(Proc) 



This function, which may be called only once before 
a "finish" or Counter Junta is done, de-activates all 
levels below levName. Thus levName specifies the 
name of the last level you wish to retain. 
(Manifest constants for the level names are in 
SysDefs.d.) It then sets the stack to a point just 
below the retained level, and calls Proc(), which 
should not return. 

The stack present at the time Junta is called is 
destroyed. The recommended procedure for saving 
data across a call to Junta is to locate the data 
below EndCode. 

A Junta always destroys the system free-storage 
pool and does not re-create it. Therefore, open 
streams, the system display and system font are all 
destroyed. The log file is closed by a Junta. 

It is the user's responsibility to take care not to 
call operating system procedures that lie in the 
region de-activated by the Junta. If in doubt, 
consult the file Sys.Bk, which documents the 
association betv/een procedures and levels. 

Any of the methods for terminating execution 
(section 3.12) automatically restores the full 
operating system. 

This function restores all de-activated sections of 
the operating system, and then calls Proc. The 
program stack present v/hen Counter Junta was 
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called is destroyed. This function is provided for 
those programs that do not wish to return to the 
operating system with a "finish," but may wish to 
do other processing (e.g., CallSubsys). 

After calling Junta, many programmers will wish to restore some of the facilities 
that the Junta destroys, such as a free storage zone, a display stream, etc. Below is 
an example of hov/ to go about this. Note that some thought is required because 
the operating system keeps a separate copy of statics from those referenced in your 
program. Thus when the OS defaults the third argument of CreateDisplayStream to 
sysFont, it uses the OS copy of sysFont, not the copy available to your program. 



JuntaQevXXXXX, Proc) 



let ProcO be 
[ 



//Make a new sysZone: 

let v=vec 7035 // You can make it any size 

v=InitializeZone(;v, 7035) 

@lvSysZone=v // Patch the os's version of the static 

sysZone=v //Patch my program's version of the static 

//Read in the system font again: 
let s=OpenFileFromFp{fpSysFont) 
let l=FileLength(s)/2 



let f =Allocate(sys2one, 1) 

Resets(s); ReadBlock(s, f, 1); Closes(s) 

sysFont=f+2 // Patch my program's version of the static 

// Note that because os's version is not patche 
// I cannot call Ws or otherwise default dsp 

//Make a display stream: 

dsp=CreateDisplayStream(6, Allocate(sysZone, 4000), sysFont) 

ShowDisplayStream(dsp, JDSalone) 



3.14. Events 

The operating system reserves a small communication region in which programs may 
record various things. The intended use for this region is the recording of events 
by one program that deserve attention by another. The Executive cooperates in 
invoking programs to deal with events posted in the communication region. 

Events are recorded sequentially in a table pointed to by the static EventVector. 
The total length of the table, available as EventVector!- 1, must not be exceeded bv 
any program generating events. Each event entry (structure EVM; see SysDefs.dj 
contains a header that specifies the type and length of the entry (length is in words 
and includes header size); following the header comes type-specific data (eventData). 
A zero word terminates the event table. 

At present, events are defined for: 

eventBooted The operating system has just been booted. 
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eventAboutToDie 
eventlnstall 

eventRFC 
eventCallSubsys 



eventlnLd 



The operating system is about to be flushed, 
probably to run a diagnostic. 

The operating system is to be re-installed. (This 
event need only be used by the Executive "Install" 
command.) 

An Ethernet request for connection has arrived 
(data in the EVM specifies the sender). 

When the next "finish" occurs, the system will try 
to execute the file whose name is given as a Bcpl 
string in the eventData block. If the eventData 
block has length 0, the system will invoke the copy 
of Ftp that is squirreled away inside Sys.Boot. 
Because a "finish" is performed right after the 
system is bootstrapped, it is possible to InLd 
Sys.Boot with a message that contains an 
eventCallSubsys, and thereby to invoke an arbitrary 
program. See the next section for a description of 
InLd. 

Whenever the next "finish" occurs, the system will 
call InLd(eventData, eventData). This suggests that 
the first words of event data should be an FPRD 
for a file you wish to InLd. 



If a program that generates an event has destroyed the event communication region, 
it is still possible to pass the event to the operating system. For example, if the 
memory diagnostic is running and an Ethernet connection request arrives, the 
mechanism can be used to load the operating system and pass the eventRFC message 
to it. The mechanism is described in the next section. 

3.15. OutLd, InLd, BootFrom 

Three functions are provided for dealing with "OutLd" files that record the entire 
state of the Alto machine, with the exception of whether interrupts are enabled. 
When the operating system is loaded with the "boot" button, such a file restores the 
machine state exactly as it was at the time of the Installation of the operating 
system. The Swat debugger also uses these facilities, saving the entire machine state 
on the file "Swatee" when a break is encountered, and restoring the Swat debugger 
state from the file "Swat." 

In the discussion that follows, an FPRD structure is like a file pointer (FP), but the 
disk address is the Real disk address of the first page of Data in the file. 

OutLd(FPRD, OutLdMessage) Saves the state of the machine on the file 

described by FPRD, which must exist and be at 
least 255 data pages long. Note that the state 
saved includes a Fk^ inside OutLd. OutLd returns 
after writing the file. Unless you know what you 
are doing, interrupts should be off when calling 
OutLd (otherwise, OutLd may save some parts oi 
the machine state, such as the Activelnterrupts 
word, that was pertinent to an interrupt in 
progress!). 



Programmers should be warned to think carefully 
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InLd(FPRD, InLdMessage) 



about the state that is being saved in an OutLd. 
For example, the operating system normally saves in 
memory some state associated with the default disk, 
sysDisk. If OutLd saves this state on a file, and 
the program is later resumed with InLd, the state 
will be incorrect. To be safe, state should be 
written out before calling OutLd (i.e., 
LogClose(sysZone); WriteDiskDescriptorQ)* and 

restored when OutLd returns (i.e., LogOpen(sysZone); 
ReadDiskDescriptorO). 

Copies the InLdMessage (length llnLdMessage) to a 
momentarily safe place and restores the machine 
state from the file described by FPRD, which must 
have been created by OutLd. Because the PC was 
in OutLd, OutLd again "returns," but this time 
with the value 1, and the InLdMessage has been 
copied into the OutLdMessage. Note: OutLd returns 
with interrupts disabled in this case. 

If the operating system boot file is InLd^ed, the 
message is assumed to be a legal data structure for 
the Even tVector, and is copied there. 

This function "boots" the Alto from the specified 
file. If it is applied to a file written by OutLd, 
the state of the machine is restored and OutLd 
"returns" 2 with interrupts disabled. (Note: The 
effect of this function differs from the effect of 
depressing the "boot" button. Unlike the boot 
button, the function in no way initializes the 
internal state of the Alto processor.) 

Some programs (e.g., DMT) will need to know how to simulate InLd or BootFrom: 

1. Turn off the display and disable interrupts. 

2. Read the first data page of the boot file into memory locations 1, 2, 
...#400. If you are loading the installed operating system, the first data 
page of the boot file is at virtual disk address 0. 

3. Store the label block for the page just read into locations #402, #403, 
...#411. 

4. (This step applies only if simulating InLd.) Now let msa=rv 2. This points 
to a location where a brief message can be stored. Set msa!0=l. Then for 
i=0 to llnLdMessage-l do msa!(i+l) = PrototypeEventVectorli. 

5. Jump to location 3, never to return. 



BootFrom(FPRD) 



4. Data structures 

This section describes the data structures used by the operating system that may be 
required by users. 



4.1. Reserved Memory Locations 

The memo "Reserved Alto Memory Locations" describes addresses reserved for various 
purposes. See also Alto Hardware Manual. 
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4.2. Streams 

The standard data structures for streams are given in the Streams package file 
"Streams.d". Documentation for the streams package includes a description. 

4.3. Disk files 

The structure of the Alto file system is described in documentation for the Alto file 
system (Disks). This includes a description of files, disk formats, directory formats, 
and the format of the disk descriptor. Bcpl declarations for these objects may be 
found in the file AltoFileSys.d. 

4.4. Display 

The data structures used to drive the Alto display are described in the Alto 
Hardware Manual. The font format for the Alto (.AL format) is also described 
there. Note: The format of the first two words of the font have changed since that 
document was last updated: 

structure AL [ 

height word //Height of chars in scan-lines 

proportional bit //True if proportional spacing used 

baseline bit 7 //# of scan-lines from top of char to baseline 

maxWidth bit 8 //Width of widest char in font 

Note that a font pointer such as the one passed to CreateDisplayStream points to 
the third word of an AL font (i.e., the "..." entry above). 

4.5. Zones 

A program that wishes to create an operating-system object and retain control over 
the allocation of storage to the object may pass a "zone" to the operating system 
function that needs space (e.g., CreateDiskStream). A zone is simply a pointer "zone" 
to a structure ZN (see SysDefs.d), with zone>>ZN.Allocate containing the address of 
the allocation procedure (called by (zone»ZN.Allocate)(zone, lengtliRequested)! and 
zone>>ZN.Free containing the address of the free procedure (called by 
(zone>>ZN.Free)(zone, block)). The zones created by the Alloc allocator package obey 
these conventions. 

The zone provided by the operating system is saved in the static sysZone. The user 
may replace the system zone by executing ©IvSysZone = value. Subsequent free- 
storage requirements for the operating system will be addressed to this zone. The 
system zone is restored when the user progi-am terminates. Warning: The operating 
system keeps various (and undocumented) information in the syvStem zone, and is 
unwilling to have the zone changed out from under it. The normal use of IvSysZone 
is to change the value of sysZone immediately after a call to Junta (which clears 
away sysZone). If you wish to create disk streams and preserve them across a call 
to Junta, pass your own zone as an argument to OpenFile. 

4.6. Operating System Status Information 

A good deal of information is retained in memory that describes the state of the 
Alto. Much of this information is of relevance to programmers, and is contained in 
some static scalars: 
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Os Version 

OsVersionCompatible 
UserName 

UserPassword 



SerialNumber 
AltoVersion 



sysDisk 



IvSysErr 



IvParitySweepCount 



IvParityPhantomEnable 



The version number of the operating system. This 
number is incremented with each new release of 
the operating system, incorporating changes however 
minor. 

The lowest operating system version number 
believed to be compatible with the present system. 

This static points to a Bcpl-format string that is 
the user's last name. It is initialized when the 
operating system is installed on the disk. The 
maximum length (in words) that the UserName may 
occupy is recorded in UserJNamei-1. 

This static points to a Bcpl-format string that is 
the user's password, typed to the Executive Login 
command. The maximum length (in words) that 
the UserPassword may occupy is recorded in 
UserPassword!- 1. 

The serial number of the Alto you are on. 

This static contains the result of executing the 
VERS instruction. Three fields of this value 
describe the Alto engineering number, the Alto 
"build" number and the microcode version. Consult 
the Alto Hardware Manual for details. 

A pointer to the DSK structure, described in 
Disks.d, which describes the "disk" to be used for 
standard operating system use. This structure is 
actually of the format BFSDSK, and contains a 
copy of the DiskDescriptor data structure. The 
static diskKd points to this structure alone 
(structure KD; see AltoFileSys.d). The storage for 
sysDisk is in levBFSwrite; if you Junta to 
levBFSbase, you will need to manufacture a new 
sysDisk structure. 

This static points to the operating-system copy of 
the static that contains the address of the error 
procedure. If you wish to replace SysErr, it 
suffices to say (§lvSysErr=Replacement. Note that 
some procedures may have already copied the value 
of SysErr (e.g., v/hen a stream is created, the value 
of SysErr is copied into the ST.error field in most 
cases). 

This static contains the address of the highest 
memory location examined when sweeping memory 
looking for parity errors. If no parity checking is 
desired, set SlvParitySweepCount = 0. 

This static points to a flag that determines 
whether phantom parity errors will invoke Swat (a 
phantom parity error results from a parity interrupt 
that can find no bad locations in memory). 
@lvParityPhantomEnable=0 will disable phantom 
reporting. 
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ErrorLogAddress 



ClockSecond 



File Hints 



Keyboard Buffer 



This, static points to a network address of a spot 
where error reports (for such things as parity 
errors) should be sent. The structure is a "port," 
as defined in Pup documentation. 

This static points to a double-precision integer that 
gives the count of number of RCLK ticks (when 
RCLK is viewed as returning a 32-bit number) in a 
second. This number is used for keeping time, and 
is nominally 1680000. If timekeeping is extremely 
critical, you may wish to calibrate yoiu- Alto and 
change this number. 

The operating system maintains file pointers for 
several commonly-used files. Using these hints in 
conjunction with OpenFile will substantially speed 
the process of opening streams. The files and file 
pointers are: 



SysDir 

SysBoot 

DiskDescriptor 

Sys.Log 

Sys.Ts 

User.Cm 

Com.Cm 

Rem.Cm 

Executive.Run 

SysFont.Al 



fpSysDir 

fpSysBoot 

f pDiskDescriptor 

fpSysLog 

fpSysTs 

fpUserCm 

fpComCm 

fpRemCm 

fpExecutive 

fpSysFont 



Although the system keyboard buffer is normally 
managed by the keyboard handler provided in the 
system, some programs may want to operate on it 
themselves. The most important instance of this is 
when a program that has done a Junta is finishing: 
if the program keeps its keyboard handler enabled, 
any characters typed during the counter-junta can 
still be recorded in the system buffer, and thus 
detected by the first program to run (usually the 
Executive). 

The static OsBuf f er points to a structure OsBUF 
(see SysDefs.d) that controls access to the buffer: 

OsBuffer»OsBUF.First First address of the ring buffer 

OsBuffer»OsBUF.Last Last address of the ring buff er+1 

OsBuffer>>OsBUF.Iri "Input" pointer (place to put next item) 

OsBuffer>>OsBUF.Out "Output" pointer (place to take next item) 

The following code can be executed with interrupts 
on or off to deal with the buffer: 

Getltem() = valof //Returns if none there! 

if OsBuffer»OsBUF.In eq OsBuffer»OsBUF.Out then resultis 

let newOut=GsBuffer»OsBUF.Out+l 

if newOut eq OsBuffer»OsBUF.Last then newOut=OsBuffer»OsBUF.First 

let result=e(OsBuffer»OsBUF.Out) 

OsBuffer»OsBUF.Out=newOut 

resultis result 
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] 

Putltem(i) = valof //Returns if buffer full already 

let newIn=OsBuffer»OsBUF.In+l 

if newin eq OsBuffer»OsBUF.Last then newIn=OsBaffer»OsBUF.First 

if newin eq OsBuffer»OsBUF.Out then resultis 

@(OsBuffer»OsBUF.In)=i 

OsBuffer»OsBUF.In=newIn 

resultis -1 

] 

GetltemCountO = valof //Returns count of items in buffer 

let c=OsBuffer»OsBUF.In-OsBuffer»OsBUF.Out 

if c Is then c=c+OsBuffer»OsBUF.Last-OsBuffer»OsBUF.First 

resultis c 

] 

ResetItemBuffer() be //Set buffer to empty 

0sBuffer»0sBUF.In=0sBuffer»OsBUF.First 
0sBuffer»0sBUF.0ut=0sBuffer»OsBUF.First 
] 

#176777 This location, the last in memory, points to the 

beginning of the area used to save statics for 
levBasic through levBcpl. The file Sys.Bk 
documents offsets from this number where the 
various statics will be found. 

4.7. Swat 

The operating system contains an interface to the Swat debugger. This interface 
uses OutLd to save the state of the machine on the file "Swatee," and InLd to 
restore the state of the machine from the file "Swat," which contains the saved 
state of the debugger itself. The inverse process is used to proceed from an 
interrupt or breakpoint. Two aspects of the Swat interface are of interest to 
programmers: 

IvAbortFlag If SlvAbortFlag is zero, holding down the <left- 

shif t> and <B3> keys will simulate the call 
OsFinish[fcAbort), thus terminating execution of the 
running program. In critical sections, setting 
©IvAbortFlag to a non-zero value will disable 
aborts. The standard convention is to increment 
©IvAbortFlag when entering such a section and to 
decrement it when exiting. This permits separate 
software modules to use the feature concurrently. 

IvSwatContextProc Although Swat saves and restores the state of the 

standard Alto I/O devices, it has no way to knov/ 
about special devices attached to the machine. The 
programmer may arrange that a (machine-language) 
procedure will be called whenever Swat is trying to 
turn off I/O preparatory to calling OutLd, or trying 
to restart I/O after an InLd. If the programmer 
does @lvSwatContextProc=DLSProc, Swat will execute 
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DLSProc(O) when turning off I/O, and DLSProcC'l) 
when turning it on. 

4.8. The Bcpl stack 

The Bcpl compiler determines the format of a frame and the calling convention. The 
strategy for allocating stack frames, however, is determined by the operating system. 
We begin by describing the compiler conventions, which are useful to know for 
writing machine-language routines. 

A procedure call: p(al, a2, ...), is implemented in the following way. The first two 
actual arguments are put into AGO and ACl (AC2 always contains the address of the 
current frame, except during a call or return). If there are exactly three actual 
arguments, the third is put into F.extraArguments. If there are more than three, the 
frame-relative address of a vector of their values is put there (except for the first 
two), so that the value of the i-th argument (counting from 1) is 
frame»F.extraArguments!rframe+i). Once the arguments are set up, code to transfer 
control is generated whicn puts the old PC into AC3 and sets the PC to p. At this 
point, ACSK) will be the number of actual arguments, and the PC should be set to 
AC3+1 to return control to the point following the call. 

A procedure declaration: let p(fl, f2, ...) be ..., declares p as a static whose value 
after loading will be the address of the instruction to which control goes when p is 
called. The first four instructions of a procedure have a standard form: 

STA 3 1,2 ; AC2»F.savedPC<-AC3 

L: JSR QGETFRAME 

number of words needed for this procedure's frame 
JSR eSTOREARGS 

The Bcpl runtime routine GETFRAME allocates storage for the new frame, NF, saves 
AC2 in NF»F.callersFrame field, sets AC2 to NF, and stores the values of AGO and 
ACl (the first two arguments) at NF>>E\f6rmals tO and 1. If there are exactly 
three actual arguments, it stores the third one also, at NF>>F.formals t2. Then, if 
there are three or fewer actual arguments, it returns to L+3, otherwise it returns to 
L+2 with the address of the vector of extra arguments in ACl; at this point a JSR 
SSTOREARGS will copy the rest of the arguments. In both cases, the number of 
actual arguments is in AGO, and this is still true after a call of STORE ARGS. A 
Bcpl procedure returns, with the result, if any, in AGO, by doing: 

JMP ©RETURN 

to a runtime routine which simply does: 

LDA 2 0,2 ; AG2<-AG2»F.callersFrame 

LDA 3 1,2 ; PG<-AC2»F.savedPG+l 

JMP 1,3 

The information above is a (hopefully) complete description of the interface between 
a Bcpl routine and the outside world (except for some additional runtime stuff which 
is supplied by the operating sj^stem). Note that it is OK to use the caller's F.Temp 
and F.extraArguments in a machine-language routine which doesn't get its own frame, 
and of course it is OK to save the PC in the caller's F.savedPC. 

The operating system currently allocates stack space contiguously and grows the stack 
down. To allocate a new frame of size S, it simply computes NF=AG2-S-2 and checks 
to see whether NF > EndCode. If not, there is a fatal error (Swat breakpoint at 
finish+1); if so, NF becomes the new frame. (Note: the "-2" in the computation is an 
unfortunate historical artifact.) 
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4.9. Run files 

The format of a file produced by Bldr to be executed by CallSubsys is described by 
the structure definition SV in SysDefs.d, Consult the Bcpl manual (section on 
Loading) for interpretations of the various fields and the handling of overlays. 

5. The Executive 

The Alto Executive is itself a subsystem and lives on the file Executive.Run; if you 
don't like it, you can v/rite your own. It is currently invoked from scratch after the 
operating system is booted, and whenever a subsystem returns. The Executive is 
fully documented in the "Alto Subsystems Manual"; only a brief description is 
presented here. 

The Executive reads a command line from the keyboard, writes it (with some 
interpretation) onto the file Com.Cm, terminated with a carriage return, and calls in 
the file named by the first word on the line (up to blank, /or carriage return). 
The interpretation is as follows: 

a) If more than one display line is needed, a command line may be -continued 
on the next display line by preceding the carriage return with a t. This t 
simply causes the carriage return to be ignored; it does not act as a 
separator. At not follovv^ed by carriage return is treated as an ordinary 
character. Line-feed characters are ignored. 

b) If the sequence @filename@ appears, the contents of the specified file are 
treated as though they had been typed in at that point, instead of the @ 
construction. This may be nested to any reasonable depth. 

c) The backspace key, or a control- A, deletes the previous undeleted character; 
a DEL deletes the whole line. A control-R retypes the line. Two slashes 
(//) begin a comment, which is terminated by the carriage return or semi- 
colon which terminates the command. 

d) Commands can be separated by semi-colons. If there is more than one 
command in a command line, everything following the first command is saved 
(after the interpretation described above) on a file called Rem.Cm, which will 
be examined the next time the Executive is run. 

The Executive has some simple commands built into it, rather than accessed through 
the subsystem machinery. These all have names of the form "xxx.--" to indicate that 
the Executive is responsible for executing them. They are handled exactly like other 
commands, but are somewhat more efficient, and cannot be overridden by changing 
the Run files with those names. . 



6. Operating Procedures 



6.1. Installing the operating system 

The "Install" command causes the operating system to execute special code which 
completely initializes the system. The options of the install procedure are controlled 
by prompts. Installation is needed: ' 
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- When a new version of the operating system is distributed. If you transfer 
the new system boot file to your disk (say as "NewOs.Boot"), you may then 
give the Install command: "Install NewOs.Boot". Several questions will be 
asked, and finally the Executive will be invoked. 

- When you wish to ERASE a disk completely and re-initialize it. This option 
pauses to let you insert the disk pack you want initialized. This "new disk" 
function is invoked by answering affirmatively the question "Do you want to 
ERASE a disk before installing?^ See also the NEWDISK section of the Alto 
Subsystems Manual. 

- When you wish to change the "owner name" or "disk name" parameters of 
the operating system. The install procedure will prompt for these strings. It 
is also possible to specify a disk password that will be checked whenever the 
operating system is booted. 

- When you wish to enable the "multiple version" feature of the file system. 
(Because few programs presently cope with all the subtleties of this feature, 
it is wise to leave it disabled.) 

When a new operating system is released, it is wise to copy it to your disk under a 
new name (e.g. NewOs.Boot). Then the command "Bootf rom NewOs.Boot" will invoke 
the new system without Installing (which would smash the present system). When 
you are finally convinced that the new system is worthy, give the command "Install 
NewOs.Boot," and respond to the installation questions. After installation, you may 
delete NewOs.Boot; the installed system is always saved on Sys.Boot. 

6.2. How to get out of trouble 

It occasionally happens that a disk will not boot, or something runs awry during the 
booting process. In this case, the following steps should be considered: 

1. Run the Scavenger. Place a good disk in the Alto, and invoke the Scavenger. 
When it asks if you wish to change disks, respond affirmatively, put the 
damaged disk in the machine and proceed when the drive becomes ready. 
When the Scavenger finishes, the attempt to invoke the Executive may fail 
because Scavenger was invoked from another disk. Try booting. If 
unsuccessful, go on to step 2. 

2. Use Ftp to get fresh copies of SysFont.Al and Executive.Run. Again, place a 
good disk in the machine and invoke Ftp. After it is initialized, change disks, 
wait for the damaged one to become ready, and type the necessary Ftp 
commands to retrieve the files. Now try booting. If unsuccessful, go to step 
3. 

3. Install. Place a good disk in the Alto and type "Install." When asked for 
your name, place the damaged disk in the machine, wait for the drive to 
become ready, and proceed. 

6.3. File Name Conventions 

Various conventions have been established for Alto file names. The conventions are 
intended to be helpful, not authorative. 

1. All files relating to a subsystem "Whiz" should have file names of the form 
"Whiz.xxx", i.e. typing "Whiz.*" to the Executive should list them all, delete them all, 
etc. Example: Bcpl.Run, Bcpl.Syms, Bcpl.YG, etc. 
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2. File extensions are of preference chosen to be lan guage extensions, i.e. they specify 
the language in which they are written. The present set is: 



Bcpl 

Mu 

Asm 

Help 

Cm 



Bcpl source code 

Micro-code source 

Assembler source code 

A help file for the system given in the name 

A command file for the Alto Executive 



3. File extensions are otherwise chosen to reflect the format . of the file, 
present set is: 



The 



Bravo 

Run 

Al 

Boot 

Br 

Syms 

Dm 

Log 
Ts 



Text file with Bravo format codes 

Executable file produced by Bldr 

Alto format font file 

A file that can be booted 

Bcpl relocatable binary file 

Bldr symbol table output 

File produced by the Dump command, 

read by the Load command 
File in "log" format 
Text file containing a transcript 



6.4. Miscellaneous information 

The key in the lower right corner of the keyboard (<blank-bottom>) is called the 
Swat key. If you press it, as well as the <ctrl> and <left-shift> keys, the Swat 
debugger will be invoked. If you do this by mistake, <ctri>P will resume your 
program without interfering with its execution, and <ctrl>K will abort your program. 

You can force an abort at any time by depressing the Swat key together with the 
<left-shift> key. 

In order for the operating system to run properly, the following files should be on 
your disk (those marked '^ are optional): 



SysDir 

DiskDescriptor 

SysFont.Al 

Executive.Run 

Sys.Boot 

Sys.Errors 

Swat 

Swatee 



System directory. 

Disk allocation table. 

System display font. 

Executive (command processor). 

Boot-file containing the operating system. 

* Error messages file. 

"^ Debugger program, created by running InstallSwat. 

* Debugging file essential to Swat. 



(Note: If you wish to change the font used by the operating system, it suffices to 
copy a new font to SysFont.Al and boot the system.) 

If you intend to write programs that use the operating system facilities, you will 
want some additional files: 



Sys.Bk 



SysDefs.d 



Required by Bldr to load programs that reference 
operating system functions. This file also shows 
which functions are implemented in which levels 
and the names of source files for the code. 
Definitions of standard system objects. You will 
probably want to "get" this file in Bcpl 
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compilations that use operating system functions 

extensively. 
Streams.d Data structure definitions relating to streams. 

AltoFileSys.d * Data structure definitions relatmg to files. 

Disks.d * Data structure definitions relating to the "disk" 

object. 



7. Differences between new and old operating systems 

This section tries to list two sorts of differences between the new and old systems: 
those functions that have been replaced by slightly different ones, and 
incompatibilities that may affect a small number of users. 

Eventually, "compatibility" with the old operating system will be abolished entirely, 
thus allowing the operating system to shrink slightly. 

Conversions 

Loading: If you use only the functions listed in this manual, it is not necessary 
to load the file INITALTOIO.Br with your program. It is likewise unnecessary 
to call an initialization procedure at the beginning of your program (as was 
the case with INITALTOIO). When loading programs for the nev/ system, the 
file Sys.Bk must be present on your disk, as Bldr reads it to generate the 
correct linkage to operating system functions. The default starting location 
for statics and code is #1000. 

Compatible loading: You may load programs just as in the old operating system 
(with INITALTOIO), but more space can be obtained by loading them lower in 
memory. However, you must not load below #1020. Thus Bldr/L/V 1020/V 
400/W 1420/0 progl.prog2 INITALTOIO is acceptable. Programs loaded in this 
fashion may also use the new functions documented in this manual. 

READVEC, WRITEVEC: Use ReadBlock, WriteBlock. The third parameter is the 
actual count (not count- 1). 

BMOVE, BSTORE: Use MoveBlock, SetBlock, Zero. Beware different calling 
sequence (source and destination exchanged, count instead of count-1). 

Creates: Use the individual functions for creating different kinds of streams. 
For disk streams, CreateDiskStream is analogous. 

SetEndCode(INITALTOIO): This call, executed after calling INITALTOIO, had the 
effect of reclaiming the space occupied by INITALTOIO. In the new system, if 
INITALTOIO is not loaded, there is no need to do this. Sys.Bk accomplishes 
the linkage to the operating system functions without requiring space in your 
program. 

SYSTEMDIR: The system directory is no longer open all the time. The call 
OpenFileFromFp(fpSysDir) will open the directory very quickly. 

#1011: This location used to point to the system font. The recommended 
method to get a pointer to the system font is GetFont(dsp3. 

Incompatibilities 

Closes: In the old system, a bug made it possible to close a stream twice. That 
is no longer possible. 
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#1002: Special interpretations were assigned to this location in the old system 
(bits on meant that Com.Cm or Rem.Cm had information in themV This is 
no longer used; the Executive examines Rem.Cm each time it is invoked. 

GetFrame: Several programs "patched" GetFrame to trap to Swat when stack 
overflow occurred. The new system calls Swat on stack overflow. If the old 
patch method is used, GetFrame is clobbered and will not operate correctly. 

#353: Several programs patched "finish" (pointed to by #353) in order to do 
cleanups before returning to the operating system. The UserFinishProc facility 
of the new operating system replaces this kluge. 

PositionPtr: This function in the new system takes a second argument that is 
the desired byte position, not desired position+2. (Note: If you load with 
INITALTOIO, a compatibility function compensates for this difference. If 
INITALTOIO is not loaded, PositionPtr will refer to the new variety.) 
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Name 



Opcode Address Function 



CYCLE 



60000 



JSRII 


64400 


D 


JSRIS 


65000 


D 


CONVERT 


67000 


D 


DIR 


61000 


- 


EIR 


61001 


- 


BRI 


61002 


- 


RCLK 


61003 


— 


SIO 


61004 


_ 


BLT 


61005 


- 



ELKS 



SIT 



61006 



61007 



JMPRAM 
RDRAM 


61010 
61011 


WRTRAM 

DIRS 

VERS 


61012 
61013 
61014 


DREAD 

DWRITE 

DEXCH 


61015 
61016 
61017 


MUL 
DIV 


61020 
61021 


BITBLT 


61024 



ACO<-ACO ley (if C ne then C else ACl); smashes 

ACl 

AC3<-PC+1; PC<-rv (rv (PC+D)} 

AC3^PC+1; PC«-rv (rv (AC2+D)) 

character scan conversion 

disable interrupts 

enable interrupts 

PC^interruptedPC; EIR 

AC0<-16 msb of clock ffrom realTimeClock); ACl^ 10 

Isb of clock * #100 + 6 bits of garbage; resolution is 

38.08 us. 

start I/O 

Block transfer of -AC3 words; ACO=address of first 

source word-1; ACl=address of last destination word; 

AGO and AC3 are updated during the instruction 

Block store of -AC3 words; ACO=data to be stored; 

ACl=address of last destination word; AC3 is updated 

during the instruction 

start interval timer. For an interrupt when the time is 

timerlnterruptTime, AGO should be 1 when this 

instruction is executed 

Emulator microcode PC<-AG1 in control RAM 

AGO<-(if AGim then RAM else R0M)!AG1 (left half if 

AGlfo], right half otherwise) 

RAM!AG1<-(AG0,AG3) 

'^' Disable interrupts and skip if interrupts v/ere on 

* AG0^((EngineeringNumber-l)'^'16 +BuildNumber)=^256 
+Microcoae Version 

** AG0^rv(AG3); AGl<-rv(AC3 xor 1) 

** rvfAGSl^AGO; rv(AG3+l)^AGl 

** t<-rvC/vG3); rv(AG3)<-AG0; ACO<-t; t<-rv(AC3+l); 

rv(AC3+l3^AGl; ACIH 

Same as NOVA MUL: AG0,l^AG2*AGl-fAC0 

Similar to NOVA DIV: AG1^AG0,1/AG2; AGO has 

remainder. DIV (unlike NOVA version) skips the next 

instruction if no overflow occurs. 

* character scan conversion of bit -map manipulation 



Notes: Address: G=bits 12-15; D=bits 8-15; -=no address 

variables in function descriptions are machine registers or page 

locations 

* indicates available only in "nev/" microcode (SIO leaves ACO[0]=0) 

** indicates available only on Alto II 



Table 2.1: New instructions in Alto emulator 
(see Alto Hardware Manual for more details) 
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Device 


Diablo 31 


Diablo 44 




Number of drives/Alto 


1 or 2 


1 




Number of packs 


1 removable 


1 removable 
1 fixed 




Number of cylinders 


203 


406 




Tracks/cylinder /pack 


2 


2 




Sectors/track 


12 


12 




Words/sector 


2 header 
8 label 
256 data 


same 




Data words/track 


3072 


3072 




Sectors/pack 


4872 


9744 




Rotation time 


40 


25 


ms 


Seek time (approx.) 


15+8.6*sqrt(dt) 


8+3*sqrt(dt) 


ms 


min-avg-max 


15-70-135 


8-30-68 


ms 


Average access 


80 


32 (both packs) 


ms 


to 1 megabyte 








Transfer rates: 








peak-avg 


1.6-1.22 


2.5-1.9 


MHz 


peak-avg 


10.2-13 


6.7-8 


US-word 


per sector 


3.3 


2.1 


ms 


for full display 


.46 


.27 


sec 


for big memory 


1.03 


.6 


sec 


whole drive 


19.3 


44 (both packs) 


sec 



Table 2.2: Properties of Alto dislcs 
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LastMemLoc 

StartSystem 

StackBase 

StackEnd 

EndCode 



StartCodeArea 
400-777 

300-377 

20-277 

0-17 



Last memory location 

Base of system 

Root of stack; stack extends downward from here 

Top of stack, which grows down 

End of user program+1 

This space contains user code and statics, loaded as 
specified by the arguments to Bldr. Default is to 
start /at StartCodeArea and load statics into the first 
400 words, and code starting at StartCodeArea+400. 
See Bcpl manual. 

Start of user program area 

Page 1: machine-dependent stuff (see Alto Hardware 
Manual) 

Bcpl runtime page 

User page 

Unused 



Table 3.1: Memory layout (all numbers octal); see section 3.6 



LastMemLoc 
StackEnd 



EndCode 
StartCodeArea 



The operating system described in this document runs 

on 64K Altos; this location is 176777. 

The address of the frame in which the current 

procedure is executing is computed by the MyFrame 

procedure; alternatively, compute Iv (first argument of 

current procedure) -4 

Rv(335) 

User code may start at any address > 777. 



Table 3.2: Values of symbolic locations in Table 3.1 
(all numbers octal) 
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Operating System Change History 



This file contains an inverse chronological listing of changes to the Alto operating 
system. 

The "normal way" to install a new operating system is to retrieve a copy of the files 
Sys.Boot, Sys.Syms, Sys.Errors and Sys.Bk that are being distributed. It is advisable 
to retrieve Sys.Boot under another name, such as NewOs.Boot and to try it out by 
saying "BootFrom NewOs.Boot" to the old system. If it seems to load properly, you 
can then invoke "Install NewOs.Boot" to install the system. After installation, 
NewOs.Boot may be deleted. 

Version 12/5 - March 20, 1977 

Additions: Clocl^econd. Location 613b is now reserved to indicate to RAM microcode 
what sort of Alto we are on: implies Alto I; -1 implies Alto II. 

Changes: Time-keeping accuracy improved slightly. BFS is now reentrant— -you may 
have several independent disk activities going concurrently (this will make CopyDisk 
more reliable). 

Version 11/5 — January 9, 1977 

Additions: eventlnLd and eventCallSubsys processing added. Also now possible to 
install the operating system with logging disabled. 

Changes: Booting process somewhat more robust. Several changes to improve 
diagnostic information about parity errors provided by Swat. Improved password 
protection. Alto II fixes in parity and timer routines. 

Version 10/5 — November 2, 1976 

Changes: A nasty bug in the disk routines was uncovered and fixed. It was 
responsible for occasionally garbaged files. 

Version 9/5 — September 25, 1976 

Additions: verNewAlways option to OpenFile; changeSerial entry on file leader pages. 

Changes: Various bugs relating to keeping file version numbers were fixed. 

Version 8/5 — August 28, 1976 

Changes: Several bugs in parity error detection and reporting were removed. 

Version 7/5 — August 10, 1976 

Additions: The Idle procedure and corresponding static Ivldle; IvParityPhantomEnable 
global static; more installation options. 

Minor changes: Two bugs in PositionPage are fixed — one permitted read-only files 
to be accidently lengthened. 

Version 6/5 — July 8, 1976 

Additions: (1) Several global statics have been added: AltoVersion (code for machine, 
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build and microcode versions], ErrorLogAddress (Ethernet address to report hardware 
errors), #176777 points to the global statics. 

(2) The format of Sys.Boot has been altered slightly so that Altos may be booted 
over the Ethernet. 

Version 5/5 — April 28, 1976 

How to get it: Because version 5 introduces some incompatibilities, it is essential 
that several subsystems be updated: (1) get a new Executive and Bravo 5.6 or later 
(these will run under version 4 or version 5 of the operating system); (2) get Sys.Bk, 
Sys.Syms, Sys.Boot (under another name, e.g. NewOs.BootJ; (3) install your new 
system; (4) get a new version of DDS, which depends on version 5 of the operating 
system; t^J get a new InstallSwat.Run and invoke it; (6) if you are a programmer, be 
sure to get new copies of all definitions files (e.g. AltoFileSys.d). 

Incompatibilities: (1) Most calling sequences • and subroutine names for the "Bfs" 
routines have changed. These changes were made in order to introduce the concept 
of a "disk" object, so that standard OS stream and directory functions could be 
applied to non-standard disks (e.g., the Trident T80). The static IvDiskKd has been 
removed. 

(2) The "disk address" returned as part of a CFA or FA is now a virtual disk 
address. The routine RealDiskDA can be used to convert it to a physical disk 
address if desired. 

Minor changes: (1) The handling of the UserFinishProc has changed. The 
recommended procedure for such procedures is to simply return from a finish 
procedure, not to call OsFinish again. 

(2^ Several bugs in the streams package are fixed, e.g. ReadBlock applied to a file 
with 511 bytes in the last data page did not work correctly. 

(3) The "new disk" refreshing procedure has been changed to use the new FTP; it is 
now mandatory that this file be present on your disk when you attempt to make a 
brand nev/ disk. 

(4) It is now possible to change disk packs during the Install sequence; simply 
change packs when some question is asked of you (exception: if you are creating a 
"new disk," do not change packs until told to do so). 

The log functions have been made much more robust. It is now possible to 
ete Sys.Log and continue operations. 

(6) Numerous bugs in ReturnFrom and FramesCaller are fixed. 

(7) The default number of file versions to keep is now stored in the DiskDescriptor. 

(8) Wns has been changed to allow both signed and unsigned number conversion. 

(9) The arguments to DeleteFile have changed slightly (only if you pass more than 2 
arguments to it). 

(10) The introduction of the "disk" object has added some statics: sysDisk, some 
functions: KsGetDisk, LnPageSize, and optional "disk" arguments to disk stream 
opening functions. 
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Operating System Software Packages 



Several of the modules of the operating system are also available as software 
packages in case the programmer wishes to include them in overlays, or modify them, 
etc. The files are contained in OS.DM, and are distributed as text files which must 
be assembled or compiled. The reason for this procedure is that proper use of these 
procedures in a foreign context may require some modifications, and will certainly 
require some understanding. 

Utilities. The file OsUtils.Bcpl contains several of the utility procedures located in 
levMain: Wss, Ws, Wl, Wns, Wos, Wo, GetFixed, FreeFixed, FixedLeft, SetEndCode. 
The procedure GetFixedlnit must be called to initialize the GetFixed/FreeFixed 
procedures. 

Password. The file Password.Bcpl contains the Alto password routines, and can be 
used to do password checking in subsystems. 

Keyboard. The keyboard handler is available in Keyboard.Bcpl and Kbhan.Asm. The 
procedure CreateKeyboardStream initializes the package, and returns a value (keys) 
that can be used as a keyboard stream-. 

Display. The display handler is available in the file Dstream.Bcpl and Dhanx.Asm. 
Documentation is found later in this manual. 

Directory. The file Dirs.Bcpl contains the directory manipulations described in section 
3.5. 

Disk Streams. The files Streams.Bcpl, StreamsMl.Asm and Log.Bcpl contain procedures 
for implementing disk streams. Documentation is found later in this manual. 

Alloc. The file Alloc.Bcpl implements the allocator. See documentation later in this 
manual. 

Basic File System. The files BfsBase.Bcpl, BfsWrite.Bcpl and BfsMl.Asm implement 
the basic file system (documentation appears later in this manual). These also need 
ReadTimer.Asm, LevelG.Asm, Dvec.Bcpl and Calls.Asm in order to operate. 
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Disk Streams: A Byte-Oriented Disk Input/Output Package 



The disk streams package provides facilities for doing efficient sequential 
input/output to and from Alto disk files. It also includes operations for doing 
random positioning with moderate efficiency, and for performing various housekeeping 
operations. An introduction to streams can be found in the Alto Operating System 
Manual. 

As part of these facilities, a "fast stream" capability permits very fast sequential 
byte access to objects stored in memory. 

The file Streams.Dm contains the source files for the disk streams package: 

Streams.D: public declarations; 

Streams.Bcpl: all the Bcpl code; 

StreamsMl.Asm: a small amount of assembly code. 

Streams use the generic procedures of a "disk object" to do disk transfers. The 
stream routines default the choice of disk to "sysDisk," a disk object created by the 
Alto operating system to provide access to the standard disk drive. However, the 
user is free to open streams to other disks. 



1. Data structures 

The file Streams.D contains the public declarations of the disk streams package. 
Most users will not be concerned with these structures (except occasionally v/ith 
their size, so as to be able to allocate the right amount of space for one of theml 
because the streams package provides procedures to perform all the operations which 
are normally needed. 

The ST structure is common to all streams in the Alto operating system. It 
includes the procedures which implement the generic stream operations for this 
particular stream: Closes, Gets, Puts, Resets, Putbacks, Errors, and Endofs. In 
addition, there is a type, which for disk streams is always stTypeDisk, and three 
parameter vvords whose interpretation depends on the stream. The parameter words 
are not used by disk streams. 

Fast streams are a specialization of streams, designed to quickly get or put bytes or 
words until a count is exhausted, and then call on a fixup routine v/hich supplies a 
new count. Usually the count specifies the number of items remaining in a buffer, 
and the fixup routine empties or refills the buffer, but no such assumptions are 
made by fast streams. This facility is described in a later section; it is used by 
disk streams, but is of no concern to a program which simply wants to use disk 
streams. 

A file pointer contains all the information required to access an Alto disk file. Its 
structure is described in detail in the Disks documentation. For a. normal user of 
streams, a file pointer is simply a small structure which must be supplied to the 
CreateDiskStream routine to specify the file to which the stream should be attached. 
File pointers are normally obtained from directories, but a user is free to store them 
wherever he wishes. 

A file address FA is a pointer to a specific byte in a file. It includes the address 
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of the byte, divided into a page number (the page size depends on the disk in use; 
normally pages contain 512 bytes) and a byte number. It also includes a disk 
address, which is a hint as to the physical location of the specified page. Stream 
routines which use file addresses check the hint; if it turns out to be correct, they 
proceed, and otherwise they start at the beginning of the file and search for the 
desired page. 

A complete file address GFA contains both a file pointer and a file address; it is a 
pointer to a specific byte anywhere in the file system. 

A file position [FPOS) is a double-precision number which addresses a byte in a file. 
The first word is the most-significant half. 

2. Properties of disk streams 

All the stream procedures take as their first parameter a structure called a disk 
stream. A disk stream provides access to a file stored on the Alto disk. Each 
stream is associated with exactly one file, although it is possible to have several 
streams in existence at once which are associated with the same file. The file is a 
permanent object, which will remain on the disk until explicitly deleted. The stream 
is an ephemeral object, which goes away when it is closed, or whenever the Alto's 
memory is erased. 

A file consists of a leader page, a length L, and a sequence of L bytes of data; each 
byte contains 8 bits. A stream is always positioned to some byte of the file, and 
the normal stream operations proceed sequentially from the current position to later 
positions in the file. The first byte is numbered 0. When the stream is positioned 
at byte n, this will be the next byte transferred by a Gets or Puts, There are also 
operations which reposition the stream. When data is written into the stream, the 
file is lengthened if necessary to make room for it. The file is never shortened 
except by TruncateDiskStream (which may be called by Closes; see below). 

A stream can transact business a word at a time or a byte at a time, depending on 
how it is created. In the former case, if the length of the file is odd, the last 
word delivered will have garbage in its right byte. 

You can replace the generic stream procedures if you wish (Gets, Puts, Closes, Resets, 
Errors, Endofs, Stateofs). The one you are most likely to want to replace is the 
error procedure. It is initialized to SysErr. .sec(Procedures) This section describes 
the calling sequences and behavior of all the user-callable procedures in the streams 
package. If a parameter is followed by an expression in brackets, this means that 
the parameter will be defaulted to that expression if you supply 0. If the last few 
parameters you are supplying are defaulted, you can just omit them. Empty brackets 
mean that the parameter may be omitted. The parameter s stands for the disk 
stream the procedure works on. 

Warning: Because the stream procedures occasionally use the RetryCall function, a 
procedure address cannot be computed, but must be the value of a static (global) or 
local variable. Thus "a>>proc(stream, b)" is not permitted, but "let pr=a»proc; 
pr(stream, b)" is fine. 

2.1. Creating and destroying 

CreateDiskStream(filePtr, type [ksTypeReadWrite], itemSize [wordlteml Cleanup 
[Noop], errRtn [SysErr], zone [sysZone], loglnfo [0], disk [sysDisly) returns 
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diskStream, A new disk stream is created and returned. It is associated with the 
file specified by filePtr on the given "disk," and positioned at item 0. Its type may 
be one of (see Streams.D for definitions): 

ksTypeReadOnly 

ksTypeWriteOnly 

ksTypeReadWrite 

Its itemSize may be one of (see Streams.D for definitions): 

charltem 
wordltem 

If you supply a cleanup routine, it will be called with the stream as parameter just 
before the stream is destroyed by a Close. If returnOnCheckError is true, the 
routine will return if the file id of the leader page at the address specified in the 
file pointer is different from the file id in the file pointer. You would want this if 
you wanted to use the file pointer as a hint, perhaps to be backed up by a 
directory lookup if it fails. In fact, the standard directory routine OpenFile does 
exactly that. If you supply a zone, it will be used to allocate the space needed by 
the stream. This space comes in two parts: the stream itself, about 60 words long, 
and the buffer, one page long. 

Resets(s): flushes any buffers associated with the stream to the disk, and positions 
the stream to 0, 

Closes(s): closes the stream, flushing the buffer and updating various information in 
the leader page if necessary. The last things it does are to call the cleanup routine 
passed to CreateDiskStream, and then to free the space for the stream. If the 
stream is open for writing only and it is not positioned at date byte 0, the file 
length is truncated to the current position. 

CleanupDiskStream(s): flushes. any buffers associated with the stream to the disk. 

2.2. Transferring Data 

Gets(s): returns the next item (byte or word, depending on the item size), or causes 
an error if there are no more items in the stream. 

Puts(s, item"): writes the next item into the stream. It causes an error if there is 
no more disK space, or if the stream was created read-only. 

ReadBlock(s, address, count) returns actualCount: reads count words from the stream 
into memory, starting at the specified memory address. It returns the number of 
words actually read, which may be less than count if there were not enough words 
in the file. It never causes an end-of -file error. It is possible to use ReadBlock on 
a byte stream, but only if the stream is currently positioned at an even byte; 
otherv/ise there will be an error. 

WriteBlock(s, address, count): writes count words from memory into the stream, 
starting at the specified memory address. The comment in ReadBlock about byte 
streams applies here also. 

2.3. Reading state 

Endofs(s): returns true if and only if there are no more items in the stream. 
LnPageSize(s) returns the log (base 2) of the number of words in a page of the file. 



For Xerox Internal Use Only — March 17, 1977 
Disk Streams January 29, 1977 44 



FileLength(s, filePos []) returns lengthL: positions the file to its last byte and 
returns the length in bytes in filePos (FPOS), and the length mod 2**16 as its 
value. 

FilePos(s, filePos []) returns posL: returns the current byte position in filePos 
(FPOS), and the current position mod 2**16 as its value. 

GetCurrentFa(s, fileAddress) stores the current position in the file address fFA), 
including the disk address of the current page as a hint which can be used by 
JumpToFa. 

GetCompleteFa(s, completeFileAddress) stores both the file pointer and the current 
position in the complete file address (CFA). This is enough information to create a 
stream (passing the file pointer to Great eDiskStr earn) and then to return to the 
current position (passing the file address to JumpToFaj. 

ReadLeaderPage(s, address) reads the leader page into memory starting at the 
specified address. The stream is left positioned at data byte 0. 

KsBufferAddress(s) returns address: returns the address in memory of the buffer for 
the stream. This is useful if you want to move the buffer; you can do so, and then 
reset the address v/ith KsSetBuffer Address. 

KsGetDisk(s) returns a pointer to the DSK object that describes the disk on v/hich 
this stream is open (see Disks documentation). 

KsHintLastPageFa(s) returns a pointer to a hint for the end of the file opened by 
stream s. 

2.4. Setting state 

TruncateDiskStream(s) truncates the stream at its current position. Afterwards, 
Endofs(s) will be true. 

PositionPage(s, page, doExtend [true^ returns wantedToExtend: positions the stream 
to byte of the specified page. It doExtend is true, it will extend the file with 
zeros if necessary in order to make it long enough to contain the specified page. If 
doExtend is false, it will not do this, but will return true if it was unable to 
position the stream as requested because the file wasn't long enough. NOTE: This 
routine interprets "page" in the units associated with the disk on which the stream 
is open. If you wish a device-independent positioning command, see SetFilePos. 

PositionPtr(s, by teNo, doExtend [true]) returns wantedtoExtend: positions the stream 
to the specified byte of the current page. DoExtend is interpreted exactly as for 
PositionPage. 

JumpToFa(s, fileAddress) positions the file to the specified address (FA). It tries to 
use the disk address hint in the address, but falls back to PositionPage if ' that fails. 

SetFilePos(s, filePos): positions the file to the byte specified by the double-precision 
number in filePos (FPOS). 

SetFilePos(s, filePosH, filePosL): positions the file to the byte specified by the 
filePosH*2^*16+filePosL. 

WriteLeaderPage(s, address) write the leader page from memory starting at the 
specified address. The stream is left positioned at data byte 0. 
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KsSetBufferAddress(s, address): sets .the buffer address to the specified memory 
address. It is the user's responsibility to be sure that the buffer has the proper 
contents, and that it was allocated from the proper zone, so that when it is freed 
using the zone which was used by CreateDiskStream the right thing will happen. 

ReleaseKs(s) will release all the storage used by the stream s, without referencing 
the disk at all. This is a way of aborting a stream, often useful when recovering 
from an unrecoverable disk error. 



3. Fast Streams 

A fast stream structure must begin with the structure declared as FS in Streams.D; 
following this the user can put anything he likes. To initialize this structure, use 

InitializeFstream(s, itemSize, PutOverflov/Routine, GetOverflowRoutine, 

GetControlCharRoutine [Noopl). The s paramter points to storage for the stream 
structure, IFS words long. The itemSize is as for CreateDiskStream. The overflow 
routines are explained below. GetControlCharRoutine(item, s) v/ill be called whenever 
a Gets for a charltem stream is about to return an item between and #37, and its 
value is returned as the value of the Gets. The initialization provides Gets, Puts, 
and Endofs routines; the other stream procedures are left as Errors. 

SetupFstream(s, wordBase, currentPos, endPos) is used to set up a fast stream to 
transfer data to or from a buffer in memory. WordBase is the address of the 
buffer in memory, and currentPos and endPos are byte addresses in the buffer. 
CurrentPos is the address of the first byte to be transferred, and endPos is the 
address of the first byte which should not be transferred. CurrentPos is rounded up 
to a word if the item size is wordltem, and endPos is rounded up to a v/ord. 

When a Gets or Puts attempts to transfer the byte addressed by endPos, the 
corresponding overflow routine is called, with the same parameters that were passed 
to the Gets or Puts. The overflov/ routine can do one of two things: 

do the work and return 

fix things up so that the Gets or Puts can succeed, and then exit with 
RetryCall{stream, item). 

SetEof(s, new Value) sets the end-of-file flag in the stream. When this flag is set, 
the Gets routine is replaced by a routine which gives an end-of-file error, and when 
it is cleared, the old Gets routine is restored. 

CuiTentPos(s) returns the current position in the buffer, always measured in bytes. 

ItemSize(s) returns the item size of the stream. 

Dirty(s) returns true if the dirty flag is true. This flag is set to true whenever a 
Puts is done. 

SetDirty(s, value) sets the dirty flag to the specified value (true or false). 



4. Errors 
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Whenever an operation on a stream causes an error, the error procedure in the 
stream is called- with two parameters: the stream, and an error code. The error 
procedure is initialized to SysErr, but the user can change it to whatever he likes. 
The error codes for errors generated by the disk stream package are: 

1301 illegal item size to CreateDiskStream or 
InitializeFstream 

1302 end of file 

1303 attempt to execute an undefined stream operation 

1200 attempt to wiite a read-only stream 

1201 attempt to do ReadBlock or WriteBlock on a stream not 

positioned at a word. 

1202 attempt to PositionPointer outside the 

range [0 .. #1000] 

1203 attempt to do a disk operation on something 

not a disk stream 

1204 bug in disk streams package 

1205 CreateDiskStream cannot allocate space for the stream 

from the zone supplied 



5. Logging File Transactions 

A small package (Log.Bcpl^ is used in conjunction with the streams package to 
maintain the system log file (Sys.Log) according to the conventions documented in 
AltoFileSys.D. The log entry types at present are (see AltoFileSys.D for definitions): 

t3rpLogFree ..an empty entry 

typLogOpenFile ..a file is being opened 

t5q)LogDeleteFile ..a file is being deleted 

typLogCreateFile ..a file is being created 

typLogRenameFile ..a file is being renamed 

MakeLo^EntryQogType, filePtr, loglnfo [0], zone [sysZone], disk [sysDisk]): makes an 
entry ot type logType in the log file, unless the filePtr structure has tne nolog bit 
on in the file serial number or the loglnfo parameter is noLog or the log file is not 
open. The FP field of the entry is filled in using the filePtr argument. If loglnfo 
is non-zero, it describes additional log information that should follow the FP in the 
entry: loglnfoll to logTnfo![logInfo!0) are the words that will be recorded. 

LogOpenfzone): Opens the log file, and leaves behind enough information so that the 
MakeLogEntry calls will be rather efficient. 

LogClose(zone): Closes the log file, and guarantees that the state of the log file on 
the disk is correct. 

The CreateDiskStream function logs a typLogOpenFile event. The Alto operating 
system closes the log and re-opens it each time a program finishes execution. 

Note: Because LogOpen saves log state in memory, it is wise to close the log before 
saving memory state on the disk (e.g., in an OutLd) and to re-open it after 
restoring. . 
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Display stream package 



A library package is now available which provides display streams of great flexibility. 
Special features include multiple fonts, repositioning to any bit position in the 
current line (or, under proper circumstances, any linej, selective erasing and polarity 
inversion, and better utilization of the available bitmap space. 

The package consists of two files, DStream.Bcpl and Dhanx.Asm. In addition, the file 
Streams.d provides useful parameter and structure declarations, in particular the 
parameters IDCB and IDS mentioned below. The package does not require any 
routines other than those in the operating system. 

1. Creating a display stream 

CreateDisplayStream(nLines, pBlock, IBlock, Font [sysFontl wWidth [38], Options 
[DScompactleft+DScompactright], zone [sysZone]): creates a display stream. nLines is 
the maximum number of lines that will be displayed at once: it is completely 
independent of the amount of space supplied for bitmap and DCBs. pBlock is the 
beginning address of storage that can be used for the display bitmap and control 
blocks; its length is IBlock. This block may be shortened slightly in order to align 
things on even word boundaries. Font is a pointer to the third word of a font in 
AL format to use for the stream. wWidth gives the width of the screen in Alto 
screen units, divided by 16; it must be an even number. Zone is a free-space pool 
from which any additional space needed by the stream can be seized. (For a 
description of zones, see the Alto OS manual.) 

The minimum space for a display stream is IDCB'^nLines+fh^wWidth+l, where fh is 
the height of the standard system font, rounded up to an even number; the +1 
allows the display stream package to align the space on an even word boundary. 
This, however, only- provides enough bitmap for a single line. A space allocation of 
lDCB'^nLines+fh*wWidth'^nLines+l guarantees enough bitmap for all nLines lines. The 
display stream package uses all the available space and then, if necessary, blanks 
lines starting from the top to make room for new data. 

Options, if supplied, controls the action of the stream under various exceptional 
conditions. The various options have mnemonic names (defined in Streams.d) and 
may be added together. Here is the list of options: 

DScompactleft allows the bitmap space required for a line to be 

reduced when scrolling by eliminating multiples of 
16 initial blank bit positions and replacing them 
with the display controller's "tab" feature. 
However, a line in which this has occurred may not 
be overwritten later (with SetLinePos, see below). 

DScompactright allows the bitmap space for a line to be reduced 

when scrolling by eliminating multiples of 16 blank 
bit positions on the right. Overv/riting is allowed 
up to the beginning of the blank space, i.e. you 
cannot make a line longer by overwriting if you 
select this option. 

DSstopright causes characters to be discarded when a line 

becomes full, rather than scrolling onto a new line. 

DSstopbottom causes characters to be discarded in preference to 
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losing data from the screen. This applies when 
either all nLines lines are occupied, or when the 
allocated bitmap space becomes full. 

DSnone none of the above (this option is necessary so that 

defaults to DScompactleft+DScompactrightJ. 

2. Displaying the stream contents 

ShowDisplayStream(s, how [DSbelow], otherStream [dsp]): This procedure controls the 
presentation of a chain of display control blocks on the screen. If how id DSbelow, 
the stream will be displayed immediately below otherStream; if DSabove, immediately 
above; if DSalone, it will be the only stream displayed; if DSdelete, the stream s will 
be removed from the screen. The third argument is not needed for DSalone or 
DSdelete. 

If you wish to construct your own "stream" for purposes of passing it to 
ShowDisplayStream, it is sufficient that s»DS.fdcb point to the first DCB of a list 
and that s>>DS.ldcb point to the last DCB. These are the only entries referenced by 
ShowDisplayStream (note that f deb and Idcb are the first two words of a stream 
structure], 

3. Current-line operations 

ResetLine(ds): erases the current line and resets the current position to the left 
margin. 

GetFont(ds): returns the current font of ds. 

SetFont(ds, pf ont): changes the font of the display stream ds. Pf ont is a pointer to 
word 2 of a font, which is compatible with GetFont. Characters v/hich have been 
written into the stream already are not affected; future characters will be written in 
the new font. If the font is higher than the font initially specified, writing 
characters may cause unexpected alteration of lines other than the line being written 
into. 

GetBitPos(ds): returns the bit position in the current line. The bit position is 
normally initialized to 8. 

SetBitPos(ds, pos): sets the bit position in the current line to pos and returns true, 
if pos is not too large; otherwise, returns false. Pos must be less than 606 (the 
display width) minus the width of the widest character in the current font. 
Resetting the bit position does not affect the bitmap; characters displayed at 
overlapping positions will be "or"ed in the obvious manner. 

EraseBits(ds, nbits, flag): changes bits in ds starting from the current position. 
Flag=0, or flag omitted, means set bits to (same as background); flag=l means set 
bits to 1 (opposite from background"); flag=-l means invert bits from their current 
state. If nbits is positive, the affected bits are those in positions pos through 
pos+nbits-1, where pos is GetBitPos(ds); if nbits is negative, the affected positions 
are pos+nbits through pos-1. In either case, the final position of the stream is 
pos+nbits. 

Here are two examples of the use of EraseBits. If the last character written on ds 
was ch, EraseBits(ds, -CharWidthfds, ch)) will erase it and back up the current 
position (see below for CharWidthJ. If a word of v/idth ww has just been written 
on ds, EraseBits(ds, -ww, -1) will change it to white-on-black. 

4. Inter-line operations 
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GetLinePos(ds): returns the line number of the current line; the top line is numbered 
0. Unlike the present operating system display streams, which always write into the 
bottom line and scroll up, the display streams provided by this package start with 
the top line and only scroll when they reach the bottom. 

SetLinePos(ds, pos): sets the current line position in ds to pos. If the line has not 
yet been written into, or if it has zero width, or if it is indented as the result of 
compacting on the left, SetLinePos has no effect and returns false; otherwise, 
SetLinePos returns true. Note that if you want to get back to where you were 
before, you must remember where that was (using GetLinePos and GetBitPos). 

InvertLine(ds, pos): Inverts the black/white sense of the line given by pos. Returns 
the old sense (O is black-on-white). 

ds»DS.cdcb: points to the DOB for the current line. You may (at your own risk) 
fiddle with this to achieve various effects. 

5. Scrolling 

The display stream package writes characters using a very fast assembly language 
routine until either the current line is full or it encounters a control character. In 
either of these situations it calls a scrolling procedure whose address is a component 
of the stream. The scrolling procedure is called with the same arguments as PUTS, 
i.e. (ds, char), and is expected to do whatever is necessary. The standard procedure 
takes the following action: 

1) Null (code 0) is ignored. 

2) New line (code 15b) causes scrolling. 

3) Tab (code lib) advances the bit position to the next multiple of 8 times 
the width of "blank" (code 40b) in the current font: if this would exceed 
the right margin, just puts out a blank. 

4) Other control characters (codes 1-lOb, 12b-14b, 16b-37b) print with 
whatever symbol appears in the font. 

5) If a character v/ill not fit on the current line, scrolling occurs and the 
character is printed at the beginning of the new line (unless the 
DSstopright option v/as chosen, in which case the character is simply 
discarded). 

The scrolling procedure is also called with arguments (ds, -1) whenever a 
contemplated scrolling operation would cause information to disappear from the 
screen, either because nLines lines are already present or because the bitmap space is 
full (unless the DSstopbottom option was chosen, in which case the procedure is not 
called and the action is the same as if it had returned false). If the procedure 
returns true, the scrolling operation proceeds normally. If the procedure returns 
false, the scrolling does not take place, and the character which triggered the 
operation is discarded. 

The user may supply a different scrolling procedure simply by filling it into the 
field ds»DS.scroll. 

6. Miscellaneous 

GetLmarg(ds): returns the left margin position of ds. The left margin is initialized 
to 8 (about 1/10" from the left edge of the screen). 

SetLmarg(ds, pos): sets the left margin of ds to pos. 

GetRmarg(ds): returns the right margin position of ds. The right margin is 
initialized to the right edge of the screen: this is the value of the displaywidth 
parameter in DISP.D. 
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SetRmarg(ds, pos): sets the right margin of ds to pos. 

CharWidth(StreamOrFont, char): returns the width of the character char in the 
stream StreamOrFont; if StreamOrFont is not a stream, it is assumed to be a font 
pointer. 



For Xerox Internal Use Only — March 17, 1977 
Alloc January 7, 1976 51 

Alloc — A Basic Storage Allocator 



WARNING: The version of Alloc described here differs markedly from that of March 
31, 1975. Beware calling sequence changes! 

The Alloc package (<ALTOSOURCE>Alloc.Bcpl for Bcpl source, <ALTO>Alloc.Br for 
relocatable binaryj contains a small and efficient non-relocating storage allocator. It 
doesn't do much, but what it does it does very well. Initially the user gives the 
allocator one (or several) blocks of storage by calls on InitializeZone. The user can 
later add storage to a zone by calling AddToZone. The function Allocate returns a 
pointer to a block allocated from a given zone. Calling Free returns a previously- 
allocated block to a given zone. 

Argument lists given belov/ are decorated with default settings. An argument 
followed by [expl will default if omitted or zero to the value exp; an argument 
followed by [...expj will default if omitted to exp. 

InitializeZone, AddToZone 

The function InitializeZone(Zone, Length, OutOfSpaceRoutine [...SysErr], 
MalFormedRoutine r...SysErr]) = zone: initializes the block of storage beginning at 
address Zone and" containing Length words to be a free storage zone. 
OutOfSpaceRoutine is taken to be an error handling routine that will be called 
whenever a requested allocation cannot be satisfied. MalFormedRoutine is an error 
printing routine that is called whenever the Alloc package detects an error in the 
consistency of the zone data structure. InitializeZone builds the zone data structure, 
and returns a pointer to a "zone," which is used for all subsequent calls to Allocate 
and Free for the zone. 

The function AddToZone(Zone, Block, Length) adds the block of storage beginning at 
Block and containing Length words to the zone pointed to by Zone. 

Alloc restricts the maximum size of the blocks it will allocate and of the "Length" 
arguments for InitializeZone and AddToZone to 32K-1. 

Allocate, Free 

The function AllocatefZone, Length, returnOnNoSpace [...0], Even [...0]) allocates a 
block of Length words from Zone and returns a pointer to that "block. If the 
allocation cannot be done, one of two cases pertains: (1) returnOnNoSpace is non-zero 
or the OutOfSpaceRoutine provided for the zone is 0: Allocate returns the value 0; if 
returnOnNoSpace is not -1, the size of the largest available block is stored in 
SreturnOnNoSpace; (2) otherwise, the value returned to the caller is the result of 
OutOf SpaceRoutine(Zone, ecOutOf Space, Length). 

If the optional parameter Even is true, the block allocated will be guaranteed to 
begin on an even word boundary. This is useful when allocating display buffers. 

The procedure Free(Zone, Block) gives a previously-allocated block of storage back to 
the zone pointed to by Zone. Block must have been the value of a call on Allocate. 

CheckZone 

The Alloc package contains considerable facilities for debugging. Conditional 
compilation will enable various levels of consistency checking; the remainder of this 
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paragraph assumes that the checking is enabled. Users should consult the source file 
(Alloc.Bcpl) for details concerning the conditional compilation. 

The procedure CheckZone(zone), which may be called conveniently from Swat, will 
perform a fairly exhaustive consistency check of the zone (provided that conditional 
compilation has caused the code to be present!). 

In addition, certain checking will be performed on the various calls to the package, 
provided that the MalFormedRoutine parameter supplied for the zone is non-zero. 

If an error is detected, the call MalFormedRoutine(zone, errCode) is executed. Values 
of the error code are: 

ecOutOfSpace 1801 Not enough space to satisfy a request. 

ecZoneAdditionError 1802 Too large or too small addition to zone. 

ecBlockNotAllocated 1803 Free has been called with a bad block. 

ecIllFormed 1804 The consistency-checker has found some 

error in the zone. Consult Alloc.Bcpl. 

Free-standing Zones 

It is often desirable to use a single 16-bit quantity to describe an entire free-space 
pool, together with its allocating and freeing procedures. For example, one can pass 
to the operating system such a quantity; the system can thereafter acquire and 
release space without knowing the details of how the operations are done. The zones 
constructed by Alloc have this property: 

zone»ZN.Allocate[zone, Length) will allocate a block 
zone»ZN.Free(zone, Block) v/ill free a block 

By convention, these entries are at the beginning of a zone. Thus, all you need to 
know about the ZN data structure is: 

structure ZN[ 

Allocate word //Allocation procedure 

Free word //Free procedure 

...rest of zone... 

] 

Example 

The following terrible implementation of the factorial function illustrates the use of 
Alloc: 

static [ Spare 

SparelsAvail 
FactZone 

] 

let Factorial(n) = valof 

[ let FactZoneV = vec 256 
let MySpare = vec 37 
Spare = MySpare 
SparelsAvail = true 

FactZone = InitializeZoneCFactZoneV, 256, StkOvfl) 

let FactVal = Inner Fact(n) 
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resultis FactVal 

3 

and InnerFact(n) = valof 

[ structure STKENT: 
[ link word 
value word 

] 

manifest [ empty = -1; 
wordsize =16 

3 

let stack = empty 

while n gr 1 do 

[ let stkent = Allocate(FactZone, size STKENT/ wordsize) 
stkent»STKENT.link = stack 
stkent»STKENT.value = n 
stack = stkent 
n = n-1 

3 

let value = 1 

while stack ne empty do 

[ value = value'Ystack»STKENT.value) 
let stkent = stack 
stack = stkent»STKENT.link 
Free[FactZone, stkent) 

resultis value 

3 

and StkOvfl(Zone, nil, Length) = valof 
[ unless SparelsAvail do 

f WsC'Aargh! Stack stuck!") 
finish 

AddToZonefFactZone, Spare, 37) 

SparelsAvau = false 

resultis AllocatefFactZone, Length) 

3 
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Disks: The Alto File System 



This document describes the disk formats used in the Alto File System. It also 
describes a "disk object," a Bcpl software construct that is used to interface low-level 
disk drivers with packages that implement higher-level objects, such as streams. 

The primary focus of the description will be for the "standard" Alto disks: either (1) 
up to 2 Diablo Model 31 disk drives or ("2) one Diablo Model 44 disk drive. The 
low-level drivers for these disks are called "Bfs" (Basic File Systeml With minor 
modifications, the description below applies to the Trident Model T50 and T80 disk 
drives, when formatted for Alto file system conventions. The differences are flagged 
with the string [Trident]. Low-level drivers for the Trident disks are called "Tfs." 



1. File and Disk Structure 

This section describes the conventions of the Alto file system. The files 
AltoFileSys.D and Bfs.D contain Bcpl structure declarations that correspond to this 
description ([Trident]: See also "Tfs.D"). 

The unit of transfer betv/een disk and memory, and hence the also of the file 
system, is the disk sector. Each sector has three fields: a 2-word header, an 8-word 
label, and a 25F=word data page. ([Trident]: The fields are a 2-word header, a 10- 
word label, and a 1024-word data page.) 

A sector is identified by a disk address; there are two kinds of disk addresses, real 
and virtual. The hardware deals in real addresses, which have a somewhat arbitrary 
format. An unfortunate consequence is that the real addresses for all the pages on 
a disk unit are sparse in the set of 16 bit integers. To correct this defect, virtual 
addresses have been introduced. They have the property that the pages of a disk 
unit which holds n pages have virtual addresses ... (n-1). Furthermore, the 
ordering of pages by virtual address is such that successive pages in the virtual 
space are usually sequential on the disk. As a result, assigning a sequence of pages 
to consecutive virtual addresses will ensure that they can be read in as fast as 
possible. 

1.1. Legal Alto Files 

An Alto file is a data structure that contains two sorts of information: some is 
mandatory, and is required for all legal files; the remainder is "hints" of various 
varieties. Programs that operate on files should endeavor to keep the hints accurate, 
but should never depend on the accuracy of a hint. 

A legal Alto file consists of a sequence of pages held together by a doubly-linked 
list recorded in the label fields. Each label contains the mandatory information: 

The forward and backward links, recorded as real disk addresses. 

A page number which gives the position of the page in the file; pages are 
numbered from 0. 

A count of the number of characters of data in the page (numchars). This may 
range from (for a completely empty page) to 512 (for a completely full page). 
([Trident]: A full page contains 2048 characters.) 
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A real file id, which is a three-word unique identifier for the file. The user 
normally deals- with virtual file ids (see the discussion of file pointers, below), 
which are automatically converted into real file ids when a label is needed. 

Three bits in the file id deserve special mention: 

Directory: This bit is on if the file is itself a directory file. This information is 
used by the disk Scavenger when trying to re-build a damaged disk data 
structure. 

Random: (This bit is currently unused.) 

NoLog: This bit is on if transactions involving this file need not be logged in 
the system log (Sys.Log). Frequently-used files of little consequence to file 
management (e.g., Com.Cm, Rem.Cm) will normally have the bit on. 

Leader Page: Page of a file is called the leader page; it contains no file data, but 
only a collection of file properties, all of which are hints. The structure LD in 
AltoFileSys.D declares the format of a leader page; it contains the file name (n.b., 
this is only a hint so that a scavenging process that attempts to rebuild the file 
system may enter this file in a directory if it is not already in one); the times for 
creation, last read and last write; a pointer to the directory in which the file is 
thought to be entered (zeroes imply the system directory SysDir); a "hint" describing . 
the last page of the file; and the "consecutive" bit which is a hint that the pages 
of the file lie at consecutive virtual disk addresses. The changeSerial field is related 
to version numbering: whenever a new version of a file "foo" is made, the 
changeSerial field of all other files "foo" (i.e., older versions) is incremented. Thus, a 
program that wishes to be sure that it is using the most recent version of a file 
can verify that changeSerial=0. If a program keeps an FP as a hint for a file, and 
is concerned about the relative position of that file in the list of version numbers, 
it can also keep and verify the changeSerial entry of the file. 

Data: The first data byte of a file is the first byte of page 1. 

In a legal file with n pages, the label field of page i must contain: 

A next link with the real disk address of page (i+1), or if i=n-l. 

A previous link with the real disk address of page (i-1), or if i=0. 

A page number between and (n-1), inclusive. 

A numchars word =512 if i<n-l, and <512 if i=n-l. The last page must not be 
completely full. ([Trident]: =2048 if i<n-l, and <2048 if i=n-l.) 

A real file id which is the same for every page in the file, and different from 
the real file id of any other file on the disk. 

A file is addressed by an object called a file pointer (FP), which is declared in 
AltoFileSys.D. A file pointer contains a virtual file id, and also the virtual address 
of the leader page of the file. The low-level disk routines construct a real file id 
from the virtual one when they must deal with a disk label. Since it is possible 
for the user to read a label from the disk and examine its contents, the drivers also 
provides a routine which will convert the real file id in the label into a file pointer 
(of course, the leader address will not be filled in). 

Note: Rear disk address (equal virtual disk address 0) cannot be part of any legal 
Alto file because the value is reserved to terminate the forward and backward 
chains in sector labels. However, disk address is used for "booting" the Alto: when 
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the boot key is pressed when no keyboard keys are down, sector is read in as a 
bootstrap loader. The normal way to make a file the "boot file" is to first create a 
legal Alto file with the bootstrap loader as the first data page (page 1), and then to 
copy this page (label and dataj into disk sector 0. Thus the label in sector 
points forward to the remainder of the boot file. 

1.2. Legal Alto Disks 

A legal disk is one on which every page is either part of a legal file, or free, or 
"permanently bad." A free page has a file id of all ones, and the rest of its label is 
indeterminate. A permanently bad page has a file id with each of the three words 
set to -2, and the remainder of the label indeterminate. 

1.3. Alto Directory Files 

A directory is a file for associating string names and FP*s. It has the directory bit 
set in its file id, and has the following format (structure DV declared in 
AltoFileSys.D). 

It is a sequence of entries. An entry contains a header and a body. The length 
field of the header tells how many words there are in the entry, including the 
header. The interpretation of the body depends on the type, recorded in the header. 

dvTypeFree=0: free entry. The body is uninterpreted. 

dvTypeFile=l: file entry. The body consists of a file pointer, followed by a Bcpl 
string containing the name of the file. The file name must contain only upper 
and lower case letters, digits, and characters in the string "+-.!$". They must 
terminate with a period (".') and not be longer than maxLengtliFn characters. If 
there are an odd number of bytes in the name, the "garbage byte" must be 0. 
The interpretation of exclamation mark (!) is special; if a file name ends with ! 
followed only by digits (and the mandatory "."), the digits specify a file version 
number. 

The main directory is a file with its leader page stored in the disk page with 
virtual address 1. There is an entry for the main directory in the main directory, 
with the name SysDir. All other directories can be reached by starting at the main 
directory. 

1.4. Disk Descriptor 

There is a file called DiskDescriptor entered in the main directory which contains a 
disk descriptor structure which describes the disk and tells which pages are free. 
The disk descriptor has two parts: a 16 word header which describes the shape of 
the disk, and a bit table indexed by virtual disk address. The declaration of this 
structure is in AltoFileSys.D. 

The "defaultVersionsKept" entry in the DiskDescriptor records the number of old 
versions of files that should be retained by the system. If this entry is 0, no 
version accounting is done: new files simply replace old ones. 

The entry in the disk descriptor named "freePages" is used to maintain a count of 
free pages on the disk (this is only a hint). 

The bit table contains a "1" corresponding to each virtual disk address that is 
believed to be occupied by a file, and "0 for free addresses. These values are, 
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however, only hints. Programs that assign new pages should check to be sure that a 
page thought to be free is indeed so by reading the label and checking to see that 
it describes a free page. (The WriteDiskPages and CreateDiskFile procedures in the 
disk class perform this checking for you.) 

1.5. The File Log 

The Alto file system makes provision for logging transactions on files in a file 

"Sys.Log." A file-management program can extract transaction information from the 

log rather than by scanning the entire directory and reading all file leader pages. A 
log entry contains: 




The time of the transaction, using the same format as that for times in the file 
leader pages. 

The file pointer (FP) for the file in question. 

Possible additional information supplied by the user. 

(Note: The low-level drivers contain no procedures for updating the log.) 

1.6. Oversights 

If the Alto file system were to be designed again, several deficiencies could be 
corrected: 

Directory entries and label entries should have the same concept of file identifier. 
Presently, we have filePointers and filelds. 

There is no reason v/hy the last page of a file cannot contain 512 bytes. 

It is unfortunate that the disk controller will not check an entry of in a label, 
because these values often arise (numChars of the last page, page number of the 
leader page). Another don't care value should be chosen: not a legal disk address; 
with enough high order bits so that it will check numChars and page number 
fields. 

The value used to terminate the chain of disk addresses stored in the labels 
should not be a legal disk address. (It should also not be zero, so that it may 
be checked.) If it is a legal address, and if you try to run the disk at full speed 
using the trick of pointing page i's label at page i-^l's disk address in the 
command block, the disk will try to read the page at the legal disk address 
represented by the chain terminator. Only when this results in an error is end 
of file detected. A terminator of zero has the undesirable property that a seek 
to track occurs whenever a chain runs into end-of-file. 



2. The Disk Object 

In order to facilitate the interface between various low-level disk drivers and higher- 
level software, we define a "disk object." A small data structure defines a number of 
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generic operations on a disk — the structure DSK is defined in "Disks.D." Each 
procedure takes the disk structure as its first argument: 

ActOnDiskPages: Used to read and write the data fields of pages of an existing 
file. 

WriteDiskPages: Used to read and write data fields of the pages of a file, and to 
extend the file if needed. 

DeleteDiskPages: Used to delete unneeded pages from the end of a file. 

CreateDiskFile: Used to create a new disk file, and to build the leader page 
correctly. 

AssignDiskPage: Used to find a free disk page and return its virtual disk address. 

ReleaseDiskPage: Used to release a virtual disk address no longer needed. 

VirtualDiskDA: Converts a real disk address into a virtual disk address. 

RealDiskDA: Converts a virtual disk address into a real disk address. 

In addition, there are several standard data entries in the DSK object: 

fpSysDir: Pointer to the FP for the directory on the disk. (This always has a 
constant format — see discussion above.) 

fpDiskDescriptor: Pointer to the FP for the file "DiskDescriptor" on the disk. 

fpSysLog: Pointer to the FP for the file "Sys.Log" on the disk (or if no log 
exists). 

fpWorkingDir: Pointer to . the FP to use as the "working directory" on this disk. 
This is usually the same as fpSysDir. 

nameWorkingDir: Pointer to a Bcpl string that contains the name of the working 
directory. 

InPageSize: This is the log (base 2) of the number of words in a data page on 
this disk. 

driveNumber: This entry identifies the drive number that this DSK structure 
describes. 

retryCount: This value gives the number of times the disk routines should retry 
an operation before declaring it an error. 

totalErrors: This value gives a cumulative count of the number of disk errors 
encountered. 

diskKd: This entry points to a copy of the DiskDescriptor in memory. Because 
the bit table can get quite large, only the header needs to be in memory. This 
header can be used, for example, to compute the capacity of the disk. 

In addition to this standard information, a particular implementation of a disk class 
may include other information in the structure. 
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3. Data Structures 

The following data structures are part of the interface between the user and the 
disk class routines: 

pageNumber: as defined in the previous section. The page number is represented by 
an integer. 

DAs: a vector indexed by page number in which the ith entry contains the virtual 
disk address of page i of the file, or one of two special values (which declared as 
manifest constants in Disks.D): 

eofDA: this page is beyond the current end of the file; 
filllnDA: the address of this page is not known. 

Note that a particular call on the file system will only reference certain elements of 
this vector, and the others do not have to exist. Thus, reading page i will cause 
references only to DAs!i and DAs!(i+l), so the user can have a two-word vector v to 
hold these quantities, and pass v-i to the file system as DAs. 

CAs: a vector indexed by page number in which the ith entry contains the core 
address to or from which page i should be transfered. The note for DAs applies 
here also. 

fp (or filePtr): file pointer, described above. In most cases, the leader page address 
is not used. 

action: a magic number which specifies what the disk should do. Possible values are 
declared as manifest constants in Disks.D: 

DCreadD: check the header and label, and read the data; 

DCwi'iteD: check the header and" label, and v/rite the data; 

DCdoNothing: 

DCseekOnly: just seek to the specified track 

DCwriteLD: check the header, write the label and data. 

A particular implementation of the disk class may also make other operations 
available by defining additional magic numbers. 



4. Subroutines 

There are two high-level calls on the basic file system: 

ActOnDiskPagesfdisk, CAs, DAs, filePtr, firstPage, lastPage, action, IvNumChars, 
lastAction, f ixedCA, cleanupRoutine, IvErrorRoutine, returnOnCheckError). Parameters 
beyond "action" are optional and may be defaulted by omitting them or making them 
0. 

Here firstPage and lastPage are the page numbers of the first and last pages to be 
acted on (i.e. read or written, in normal use). This routine does the specified action 
on each page and returns the page number of the last page successfully acted on. 
This may be less than lastPage if the file turns out to have fewer pages. 
DAslfirstPage must contain a disk address, but any of DAs!(firstPage-Hl3 through 
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DAs!(lastPage+l) may be filllnDA, in .which case it will be replaced with the actual 
disk address, as determined from the chain when the labels are read. Note that the 
routine v/ill fill in DAs!(lastPage+l), so this word must exist. 

The value of the numChars field in the label of the last page acted on will be left 
in rv IvNumChars. If lastAction is supplied, it will be used as the action for 
lastPage instead of action. If CAs eq 0, f ixedCA is used as the core address for all 
the data transfers. If cleanupRoutine is supplied, it is called with the command 
block (see below) as a parameter after the successful completion of each disk 
command (Note: providing a cleanup routine defeats the automatic filling in of disk 
addresses in DAs). 

Disk transfers that generate errors are retried several times and then the error 
routine is called with 

rv lvErrorRoutine(lvErrorRoutine, cb, errorCode) 

In other words, IvErrorRoutine is the address of a word which contains the (address 
of the) routine to be called when there is an error. The errorCode tells v/hat kind 
of error it was; the standard error codes are tabulated in a later section. The cb is 
the control block which caused the error; its format depends on the particular 
implementation of the drivers (Bfs: the structure CB in Bfs.D). 

The intended use of IvErrorRoutine is this. A disk stream contains a cell A, in a 
known place in the stream structure, which contains the address of a routine which 
fields disk errors. The address of A is passed as IvErrorRoutine. "V^Txen the error 
routine is called, it gets the address of A as a parameter, and by subtracting the 
kno'^Am position of A in the disk stream structure, it can obtain the address of the 
stream structure, and thus determine which stream caused the error. 

The default value of returnOnCheckError is false. If returnOnCheckError is true and 
an error is encountered, ActOnDiskPages will not retry a check error and then report 
an error. Instead, it will return -(#100+i), where i is the page number of the last 
page successfully transferred. This feature allows ActOnDiskPages to be used when 
the user it not sure whether the disk address he has is correct. It is used by the 
disk stream and directory routines which take hints; they try to read from the page 
addressed by the hint with returnOnCheckError true, and if they get a normal return 
they know that the hint was good. On the other hand, if it was not good, they 
will get the abnormal return just described, and can proceed to try again m a more 
conservative way. Note that the label is not rewritten by DCwriteD, so that the 
number of characters per page will not change. If you need to change the label, you 
should use WriteDiskPages unless you know what you are doing. 

ActOnDiskPages can be used to both read and write a file as long as the length of 
the file does not have to change. If it does, you must use WriteDiskPages. 



WriteDiskPagesfdisk, CAs, DAs, filePtr, firstPage, lastPage, lastAction, IvNumChars, 
lastNumChars, fixedCA, nil, IvErrorRoutine). Arguments beyond lastPage are optional 
and may be defaulted by omitting them or making them (but lastNumChars is not 
defaulted if it is 0). 

This routine writes the specified pages from CAs (or from fixedCA if CAs is 0, as 
for ActOnDiskPages). It fills in DAs entries in the same way as ActOnDiskPages, 
and also allocates enough new pages to complete the specified write. The numChars 
field in the label of the last page will be set to lastNumChars (which defaults to 
512 [Trident]: 2048). It is not necessary for DAsifirstPage to contain a disk address; 
it may be filllnDA, and a new page will be allocated. 
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In most cases, DAs!(firstPage-l) should have the value which you want written into 
the backward chain pointer for firstPage, since this value is needed whenever the 
label for firstPage needs to be rewritten. The only case in which it doesn't need to 
be rewritten is when the page is already allocated, the next page is not being 
allocated, and the numChars field is not changing. 

If lastPage already exists: 

1) the old value of the numGhars field of its label is left in rv IvNumChars. 

2) if lastAction is supplied, it is applied to lastPage instead of DCwriteD. It 
defaults to DCwriteD. 

WriteDiskPages handles one special case to help in "renaming" files, i.e. in changing 
the FP (usually the serial number) of all the pages of a file. To do this, use 
ActOnDiskPages to read a number of pages of the file into memory and to build a 
DAs array of valid disk addresses. Then a call to WriteDiskPages with lastAction=-l 
will write labels and data for pages firstPage through lastPage (DAs!(firstPage~l) and 
DAsiriastPage+l) are of course used in this writing process). The numChars field of 
the label on the last page is set to lastNumChars. To use this facility, the entire 
DAs array must be valid, i.e. no entries may be filllnDA. 



In addition to these two routines, there are two others which provide more 
specialized services: 

CreateDiskFile(disk, name, filePtr, dirFilePtr, wordl [0], useOldFp [false]) creates a 
new disk file and writes its leader page. It returns the serial number and leader 
disk address in the FP structure f ilePtr. A newly created file has one data page 
(page 1) with numChars eq 0. 

The arguments beyond filePtr are optional, and have the following significance: 

If dirFilePtr is supplied, it should be a file pointer to the directory which owns 

the file. This file pointer is written into the leader page, and is used by the 

disk Scavenger to put the file back into the directory if it becomes lost. It 

defaults to the main (root) directory. 

The value of wordl is "or"ed into the filePtr»FP.serialNumber.wordl portion of 
the file pointer. This allows the directory, random, or nolog bits to be set in 
the file id. 

if useOldFp is true, then filePtr already points to a legal file; the purpose of 
calling CreateDiskFile is to re-write all the labels of the existing file with the 
new serial number, and to re-initialize the leader page. The data contents of the 
original file are lost. Note that this process effectively "deletes" the file described 
by filePtr when CreateDiskFile is called, and makes a new file; the FP for the 
new file is returned in filePtr. 

DeleteDiskPages(disk, CA, firstDA, filePtr, firstPage) deletes the pages of a file, 
starting with the page whose number is firstPage and whose disk address is firstDA. 
CA is a page-sized buffer which is clobbered by the routine. 
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5, Allocating Disk Space 

The disk class also contains routines for allocating space and for converting between 
virtual and real disk addresses. In most cases, users need not call these routines 
directly, as the four routines given above (ActOnDiskPages, WriteDiskPages, 
DeleteDiskPages, CreateDiskFile) manage disk addresses and disk space internally. 

AssignDiskPage(disk, virtualDA) returns the virtual disk address of the first free page 
following virtualDA, according to the bit table, and sets the corresponding bit. It 
does not do any checking that the page is actually free (but WriteDiskPages does). 
If there are no free pages it returns -1. 

ReleaseDiskPage(disk, virtualDA) marks the page as free in the bit table. It does 
not write anything on the disk (but DeleteDiskPages does). 

VirtualDiskDA(disk, IvRealDA) returns the virtual disk address, given a real disk 
address in rv IvRealDA. (The address, IvRealDA, is passed because a real disk 
address may occupy more than 1 word.) 

RealDiskDA(disk, virtualDA, IvRealDA) computes the real disk address and stores it in 
rv IvRealDA. The function returns true if the virtual disk address is legal, i.e. 
within the bounds of disk addresses for the given "disk." Otherwise, it returns false. 



6. Error Codes 



The following errors may be generated by the disk object: 

1101 unrecoverable disk error 

1102 disk full 



7. Implementation — Bfs 

Bfs ("Basic File System") is the name for a package of routines that implement the 
disk class for the standard Alto disks (either Diablo Model 31 drives or a single 
Diablo Model 44 drive). The definitions (in addition to those in AltoFileSys.D and 
Disks.D) are contained in Bfs.D. The code comes in two "levels:" a "base" for reading 
and writing existing files (implements ActOnDiskPages, RealDisldDA and VirtualDiskDA 
only); and a "write" level for creating, deleting, lengthening and shortening files 
(implements V/riteDiskPages, CreateDiskFile, DeleteDiskPages, AssignDiskPage, 
ReleaseDiskPage). The source files BfsBase.Bcpl, Dvec.Bcpl and BfsMLAsm comprise 
the base level; Bfs Write.Bcpl implements the v/rite level. 

The implementation expects a structure BFSDSK to be passed as the "disk" argument 
to the routines. The initial portion of this structure is the standard DSK structure; 
the final portion is a copy of the DiskDescriptor file for the disk in use. (Note: 
The Alto operating system maintains a static sysDisk that points to such a structure 
for disk drive 0.) 

It is also possible to use the Bfs at a lower level. This level uses two data 
structures, zones (defined by the structure CBZ) and control blocks (cb's, defined by 
the structure CB). The general idea is that a zone is set ujp with disk command 
blocks in it. A free block is obtained from the zone with BfsGetCb and sent to the 
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disk with BfsDoDiskCommand. When ^ it is sent to the disk, it is also put on the 
queue which BfsGetCb uses, but BfsGetCb waits until the disk is done with the 
command before returning it, and also checks for errors. 

If you plan to use these routines, read the code for ActOnDiskPages to find out how 
they are intended to be called. 

BfsInitializeCbStorage(disk, zone, firstPage, length, retry, IvErrorRoutine). Zone is the 
address of a block of length words which can be used to store cb's. It takes at 
least three cb's to run the disk at full speed; CBzoneLength is a constant which 
gives the size of a zone which can hold three cb's. FirstPage is used to initialize 
the currentPage field of the zone. Retry is used to initialize the retry fields of all 
the cb's. The arguments after firstPage can be omitted if a zone is being 
reinitialized, and they will remain unchanged from the previous initialization. 

BfsGetCbfdisk, zone, dontClear) returns the next cb for the zone. If the next cb is 
still on the disk command queue, the routine waits until the disk has finished with 
it. Before returning a cb, BfsGetCb checks for errors. If it finds one, it increments 
zone>>CBZ.errorCount. If this number is ge the value disk»DSK.retryCount, BfsGetCb 
calls the error routine which was passed to BfsInitializeCbStorage; the way this is 
done is explained in the description of ActOnDiskPages above. Otherwise, after doing 
a restore on the disk if errorCount ge disk>>DSK.retryCount/2, it reinitializes the 
zone with firstPage equal to the page with the error, and returns to cb»CB.retry 
instead of returning normally. The idea is that the code there will retry all the 
incomplete commands. If there is no error, cb»CB.cleanupRoutine is called (if it is 
non-zero) with cb as its argument. Then the numChars field of the label is copied 
into the currentNumChars field of the zone, and the errorCount field of the zone is 
cleared. Next, unless the optional argument dontClear is true, the cb is zeroed. 
Finally, the cb is returned as the value of BfsGetCb. 

BfsDoDiskCommand(disk, cb, CA, DA, filePtr, pageNumber, action) Constructs a disk 
command in cb with data address C A, virtual disk address DA, serial and version 
number taken from the virtual file id in filePtr, page number taken from 
pageNumber, and disk command specified by action. It expects the cb to be zeroed, 
except that the following fields may be preset; if they are zero the indicated default 
is supplied: 

labelAddress Iv cb»CB.label 

numChars 

normalWakeups cb>>CB.zone>>CBZ.normalWakeups 

error Wakeups cb»CB.zone»CBZ.errorWakeups 

If DA eq filllnDA, the DA field is not set; presumably it is the target of the label 
for a previous command. Actions are checked for legality. 

Bf sMakeFpFromLabel(f p, la) constructs a virtual file id in the file pointer fp from 
the real file id in the label la. 



8. Implementation -- • Tfs 

Operation and implementation of the Trident T80 disks is described in separate 
documentation under the heading "TFS/TFU" in Alto Subsystems documentation. 
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